← Back to branch summary

~ubuntu-branches/ubuntu/raring/sflphone/raring

« back to all changes in this revision

Viewing changes to sflphone-common/libs/pjproject/pjnath/include/pjnath/stun_session.h

  • Committer: Package Import Robot
  • Author(s): Francois Marier
  • Date: 2011-11-25 13:24:12 UTC
  • mfrom: (4.1.10 sid)
  • Revision ID: package-import@ubuntu.com-20111125132412-dc4qvhyosk74cd42
Tags: 1.0.1-4
http://bugs.debian.org/649726
Don't assume that arch:all packages will get built (closes: #649726)

Show diffs side-by-side

added added

removed removed

Lines of Context:
sflphone-common/libs/pjproject/pjnath/include/pjnath/stun_session.h
1
 
/* $Id: stun_session.h 2724 2009-05-29 13:04:03Z bennylp $ */
2
 
/* 
3
 
 * Copyright (C) 2008-2009 Teluu Inc. (http://www.teluu.com)
4
 
 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5
 
 *
6
 
 * This program is free software; you can redistribute it and/or modify
7
 
 * it under the terms of the GNU General Public License as published by
8
 
 * the Free Software Foundation; either version 2 of the License, or
9
 
 * (at your option) any later version.
10
 
 *
11
 
 * This program is distributed in the hope that it will be useful,
12
 
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13
 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14
 
 * GNU General Public License for more details.
15
 
 *
16
 
 * You should have received a copy of the GNU General Public License
17
 
 * along with this program; if not, write to the Free Software
18
 
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
19
 
 *
20
 
 *  Additional permission under GNU GPL version 3 section 7:
21
 
 *
22
 
 *  If you modify this program, or any covered work, by linking or
23
 
 *  combining it with the OpenSSL project's OpenSSL library (or a
24
 
 *  modified version of that library), containing parts covered by the
25
 
 *  terms of the OpenSSL or SSLeay licenses, Teluu Inc. (http://www.teluu.com)
26
 
 *  grants you additional permission to convey the resulting work.
27
 
 *  Corresponding Source for a non-source form of such a combination
28
 
 *  shall include the source code for the parts of OpenSSL used as well
29
 
 *  as that of the covered work.
30
 
 */
31
 
#ifndef __PJNATH_STUN_SESSION_H__
32
 
#define __PJNATH_STUN_SESSION_H__
33
 
 
34
 
/**
35
 
 * @file stun_session.h
36
 
 * @brief STUN session management for client/server.
37
 
 */
38
 
 
39
 
#include <pjnath/stun_msg.h>
40
 
#include <pjnath/stun_auth.h>
41
 
#include <pjnath/stun_config.h>
42
 
#include <pjnath/stun_transaction.h>
43
 
#include <pj/list.h>
44
 
#include <pj/timer.h>
45
 
 
46
 
PJ_BEGIN_DECL
47
 
 
48
 
 
49
 
/* **************************************************************************/
50
 
/**
51
 
 * @addtogroup PJNATH_STUN_SESSION
52
 
 * @{
53
 
 *
54
 
 * This is is a transport-independent object to manage a client or server 
55
 
 * STUN session. It has the following features:
56
 
 * 
57
 
 *  - <b>transport independent</b>:\n
58
 
 *    the object does not have it's own socket, but rather it provides
59
 
 *    functions and callbacks to send and receive packets. This way the
60
 
 *    object can be used by different transport types (e.g. UDP, TCP, 
61
 
 *    TLS, etc.) as well as better integration to application which
62
 
 *    already has its own means to send and receive packets.
63
 
 * 
64
 
 *  - <b>authentication management</b>:\n
65
 
 *    the object manages STUN authentication throughout the lifetime of
66
 
 *    the session. For client sessions, once it's given a credential to
67
 
 *    authenticate itself with the server, the object will automatically
68
 
 *    add authentication info (the MESSAGE-INTEGRITY) to the request as
69
 
 *    well as authenticate the response. It will also handle long-term 
70
 
 *    authentication challenges, including handling of nonce expiration,
71
 
 *    and retry the request automatically. For server sessions, it can 
72
 
 *    be configured to authenticate incoming requests automatically.
73
 
 *  
74
 
 *  - <b>static or dynamic credential</b>:\n
75
 
 *    application may specify static or dynamic credential to be used by
76
 
 *    the STUN session. Static credential means a static combination of
77
 
 *    username and password (and these cannot change during the session
78
 
 *    duration), while dynamic credential provides callback to ask the
79
 
 *    application about which username/password to use everytime
80
 
 *    authentication is about to be performed.
81
 
 *    
82
 
 *  - <b>client transaction management</b>:\n
83
 
 *    outgoing requests may be sent with a STUN transaction for reliability,
84
 
 *    and the object will manage the transaction internally (including
85
 
 *    performing retransmissions). Application will be notified about the
86
 
 *    result of the request when the response arrives (or the transaction
87
 
 *    times out). When the request is challenged with authentication, the
88
 
 *    object will retry the request with new authentication info, and 
89
 
 *    application will be notified about the final result of this request.
90
 
 * 
91
 
 *  - <b>server transaction management</b>:\n
92
 
 *    application may ask response to incoming requests to be cached by
93
 
 *    the object, and in this case the object will check for cached
94
 
 *    response everytime request is received. The cached response will be
95
 
 *    deleted once a timer expires.
96
 
 *
97
 
 * \section using_stun_sess_sec Using the STUN session
98
 
 *
99
 
 * The following steps describes how to use the STUN session:
100
 
 *
101
 
 *  - <b>create the object configuration</b>:\n
102
 
 *    The #pj_stun_config contains the configuration to create the STUN
103
 
 *    session, such as the timer heap to register internal timers and
104
 
 *    various STUN timeout values. You can initialize this structure by
105
 
 *    calling #pj_stun_config_init()
106
 
 *
107
 
 *  - <b>create the STUN session</b>:\n
108
 
 *    by calling #pj_stun_session_create(). Among other things, this
109
 
 *    function requires the instance of #pj_stun_config and also 
110
 
 *    #pj_stun_session_cb structure which stores callbacks to send
111
 
 *    outgoing packets as well as to notify application about incoming
112
 
 *    STUN requests, responses, and indicates and other events.
113
 
 *
114
 
 *  - <b>configure credential:</b>\n
115
 
 *    if authentication is required for the session, configure the
116
 
 *    credential with #pj_stun_session_set_credential()
117
 
 *
118
 
 *  - <b>configuring other settings:</b>\n
119
 
 *    several APIs are provided to configure the behavior of the STUN
120
 
 *    session (for example, to set the SOFTWARE attribute value, controls
121
 
 *    the logging behavior, fine tune the mutex locking, etc.). Please see
122
 
 *    the API reference for more info.
123
 
 *
124
 
 *  - <b>creating outgoing STUN requests or indications:</b>\n
125
 
 *    create the STUN message by using #pj_stun_session_create_req() or
126
 
 *    #pj_stun_session_create_ind(). This will create a transmit data
127
 
 *    buffer containing a blank STUN request or indication. You will then
128
 
 *    typically need to add STUN attributes that are relevant to the
129
 
 *    request or indication, but note that some default attributes will
130
 
 *    be added by the session later when the message is sent (such as
131
 
 *    SOFTWARE attribute and attributes related to authentication).
132
 
 *    The message is now ready to be sent.
133
 
 *
134
 
 *  - <b>sending outgoing message:</b>\n
135
 
 *    use #pj_stun_session_send_msg() to send outgoing STUN messages (this
136
 
 *    includes STUN requests, indications, and responses). The function has
137
 
 *    options whether to retransmit the request (for non reliable transports)
138
 
 *    or to cache the response if we're sending response. This function in 
139
 
 *    turn will call the \a on_send_msg() callback of #pj_stun_session_cb 
140
 
 *    to request the application to send the packet.
141
 
 *
142
 
 *  - <b>handling incoming packet:</b>\n
143
 
 *    call #pj_stun_session_on_rx_pkt() everytime the application receives
144
 
 *    a STUN packet. This function will decode the packet and process the
145
 
 *    packet according to the message, and normally this will cause one
146
 
 *    of the callback in the #pj_stun_session_cb to be called to notify
147
 
 *    the application about the event.
148
 
 *
149
 
 *  - <b>handling incoming requests:</b>\n
150
 
 *    incoming requests are notified to application in the \a on_rx_request
151
 
 *    callback of the #pj_stun_session_cb. If authentication is enabled in
152
 
 *    the session, the application will only receive this callback after
153
 
 *    the incoming request has been authenticated (if the authentication
154
 
 *    fails, the session would respond automatically with 401 error and
155
 
 *    the callback will not be called). Application now must create and
156
 
 *    send response for this request.
157
 
 *
158
 
 *  - <b>creating and sending response:</b>\n
159
 
 *    create the STUN response with #pj_stun_session_create_res(). This will
160
 
 *    create a transmit data buffer containing a blank STUN response. You 
161
 
 *    will then typically need to add STUN attributes that are relevant to
162
 
 *    the response, but note that some default attributes will
163
 
 *    be added by the session later when the message is sent (such as
164
 
 *    SOFTWARE attribute and attributes related to authentication).
165
 
 *    The message is now ready to be sent. Use #pj_stun_session_send_msg()
166
 
 *    (as explained above) to send the response.
167
 
 *
168
 
 *  - <b>convenient way to send response:</b>\n
169
 
 *    the #pj_stun_session_respond() is provided as a convenient way to
170
 
 *    create and send simple STUN responses, such as error responses.
171
 
 *    
172
 
 *  - <b>destroying the session:</b>\n
173
 
 *    once the session is done, use #pj_stun_session_destroy() to destroy
174
 
 *    the session.
175
 
 */
176
 
 
177
 
 
178
 
/** Forward declaration for pj_stun_tx_data */
179
 
typedef struct pj_stun_tx_data pj_stun_tx_data;
180
 
 
181
 
/** Forward declaration for pj_stun_rx_data */
182
 
typedef struct pj_stun_rx_data pj_stun_rx_data;
183
 
 
184
 
/** Forward declaration for pj_stun_session */
185
 
typedef struct pj_stun_session pj_stun_session;
186
 
 
187
 
 
188
 
/**
189
 
 * This is the callback to be registered to pj_stun_session, to send
190
 
 * outgoing message and to receive various notifications from the STUN
191
 
 * session.
192
 
 */
193
 
typedef struct pj_stun_session_cb
194
 
{
195
 
    /**
196
 
     * Callback to be called by the STUN session to send outgoing message.
197
 
     *
198
 
     * @param sess          The STUN session.
199
 
     * @param token         The token associated with this outgoing message
200
 
     *                      and was set by the application. This token was 
201
 
     *                      set by application in pj_stun_session_send_msg()
202
 
     *                      for outgoing messages that are initiated by the
203
 
     *                      application, or in pj_stun_session_on_rx_pkt()
204
 
     *                      if this message is a response that was internally
205
 
     *                      generated by the STUN session (for example, an
206
 
     *                      401/Unauthorized response). Application may use
207
 
     *                      this facility for any purposes.
208
 
     * @param pkt           Packet to be sent.
209
 
     * @param pkt_size      Size of the packet to be sent.
210
 
     * @param dst_addr      The destination address.
211
 
     * @param addr_len      Length of destination address.
212
 
     *
213
 
     * @return              The callback should return the status of the
214
 
     *                      packet sending.
215
 
     */
216
 
    pj_status_t (*on_send_msg)(pj_stun_session *sess,
217
 
                               void *token,
218
 
                               const void *pkt,
219
 
                               pj_size_t pkt_size,
220
 
                               const pj_sockaddr_t *dst_addr,
221
 
                               unsigned addr_len);
222
 
 
223
 
    /** 
224
 
     * Callback to be called on incoming STUN request message. This function
225
 
     * is called when application calls pj_stun_session_on_rx_pkt() and when
226
 
     * the STUN session has detected that the incoming STUN message is a
227
 
     * STUN request message. In the 
228
 
     * callback processing, application MUST create a response by calling
229
 
     * pj_stun_session_create_response() function and send the response
230
 
     * with pj_stun_session_send_msg() function, before returning from
231
 
     * the callback.
232
 
     *
233
 
     * @param sess          The STUN session.
234
 
     * @param pkt           Pointer to the original STUN packet.
235
 
     * @param pkt_len       Length of the STUN packet.
236
 
     * @param rdata         Data containing incoming request message.
237
 
     * @param token         The token that was set by the application when
238
 
     *                      calling pj_stun_session_on_rx_pkt() function.
239
 
     * @param src_addr      Source address of the packet.
240
 
     * @param src_addr_len  Length of the source address.
241
 
     *
242
 
     * @return              The return value of this callback will be
243
 
     *                      returned back to pj_stun_session_on_rx_pkt()
244
 
     *                      function.
245
 
     */
246
 
    pj_status_t (*on_rx_request)(pj_stun_session *sess,
247
 
                                 const pj_uint8_t *pkt,
248
 
                                 unsigned pkt_len,
249
 
                                 const pj_stun_rx_data *rdata,
250
 
                                 void *token,
251
 
                                 const pj_sockaddr_t *src_addr,
252
 
                                 unsigned src_addr_len);
253
 
 
254
 
    /**
255
 
     * Callback to be called when response is received or the transaction 
256
 
     * has timed out. This callback is called either when application calls
257
 
     * pj_stun_session_on_rx_pkt() with the packet containing a STUN
258
 
     * response for the client transaction, or when the internal timer of
259
 
     * the STUN client transaction has timed-out before a STUN response is
260
 
     * received.
261
 
     *
262
 
     * @param sess          The STUN session.
263
 
     * @param status        Status of the request. If the value if not
264
 
     *                      PJ_SUCCESS, the transaction has timed-out
265
 
     *                      or other error has occurred, and the response
266
 
     *                      argument may be NULL.
267
 
     *                      Note that when the status is not success, the
268
 
     *                      response may contain non-NULL value if the 
269
 
     *                      response contains STUN ERROR-CODE attribute.
270
 
     * @param token         The token that was set by the application  when
271
 
     *                      calling pj_stun_session_send_msg() function.
272
 
     *                      Please not that this token IS NOT the token
273
 
     *                      that was given in pj_stun_session_on_rx_pkt().
274
 
     * @param tdata         The original STUN request.
275
 
     * @param response      The response message, on successful transaction,
276
 
     *                      or otherwise MAY BE NULL if status is not success.
277
 
     *                      Note that when the status is not success, this
278
 
     *                      argument may contain non-NULL value if the 
279
 
     *                      response contains STUN ERROR-CODE attribute.
280
 
     * @param src_addr      The source address where the response was 
281
 
     *                      received, or NULL if the response is NULL.
282
 
     * @param src_addr_len  The length of the source  address.
283
 
     */
284
 
    void (*on_request_complete)(pj_stun_session *sess,
285
 
                                pj_status_t status,
286
 
                                void *token,
287
 
                                pj_stun_tx_data *tdata,
288
 
                                const pj_stun_msg *response,
289
 
                                const pj_sockaddr_t *src_addr,
290
 
                                unsigned src_addr_len);
291
 
 
292
 
 
293
 
    /**
294
 
     * Callback to be called on incoming STUN request message. This function
295
 
     * is called when application calls pj_stun_session_on_rx_pkt() and when
296
 
     * the STUN session has detected that the incoming STUN message is a
297
 
     * STUN indication message.
298
 
     *
299
 
     * @param sess          The STUN session.
300
 
     * @param pkt           Pointer to the original STUN packet.
301
 
     * @param pkt_len       Length of the STUN packet.
302
 
     * @param msg           The parsed STUN indication.
303
 
     * @param token         The token that was set by the application when
304
 
     *                      calling pj_stun_session_on_rx_pkt() function.
305
 
     * @param src_addr      Source address of the packet.
306
 
     * @param src_addr_len  Length of the source address.
307
 
     *
308
 
     * @return              The return value of this callback will be
309
 
     *                      returned back to pj_stun_session_on_rx_pkt()
310
 
     *                      function.
311
 
     */
312
 
    pj_status_t (*on_rx_indication)(pj_stun_session *sess,
313
 
                                    const pj_uint8_t *pkt,
314
 
                                    unsigned pkt_len,
315
 
                                    const pj_stun_msg *msg,
316
 
                                    void *token,
317
 
                                    const pj_sockaddr_t *src_addr,
318
 
                                    unsigned src_addr_len);
319
 
 
320
 
} pj_stun_session_cb;
321
 
 
322
 
 
323
 
/**
324
 
 * This structure describes incoming request message.
325
 
 */
326
 
struct pj_stun_rx_data
327
 
{
328
 
    /**
329
 
     * The parsed request message.
330
 
     */
331
 
    pj_stun_msg             *msg;
332
 
 
333
 
    /**
334
 
     * Credential information that is found and used to authenticate 
335
 
     * incoming request. Application may use this information when 
336
 
     * generating  authentication for the outgoing response.
337
 
     */
338
 
    pj_stun_req_cred_info   info;
339
 
};
340
 
 
341
 
 
342
 
/**
343
 
 * This structure describe the outgoing STUN transmit data to carry the
344
 
 * message to be sent.
345
 
 */
346
 
struct pj_stun_tx_data
347
 
{
348
 
    /** PJLIB list interface */
349
 
    PJ_DECL_LIST_MEMBER(struct pj_stun_tx_data);
350
 
 
351
 
    pj_pool_t           *pool;          /**< Pool.                          */
352
 
    pj_stun_session     *sess;          /**< The STUN session.              */
353
 
    pj_stun_msg         *msg;           /**< The STUN message.              */
354
 
 
355
 
    void                *token;         /**< The token.                     */
356
 
 
357
 
    pj_stun_client_tsx  *client_tsx;    /**< Client STUN transaction.       */
358
 
    pj_bool_t            retransmit;    /**< Retransmit request?            */
359
 
    pj_uint32_t          msg_magic;     /**< Message magic.                 */
360
 
    pj_uint8_t           msg_key[12];   /**< Message/transaction key.       */
361
 
 
362
 
    pj_stun_req_cred_info auth_info;    /**< Credential info                */
363
 
 
364
 
    void                *pkt;           /**< The STUN packet.               */
365
 
    unsigned             max_len;       /**< Length of packet buffer.       */
366
 
    pj_size_t            pkt_size;      /**< The actual length of STUN pkt. */
367
 
 
368
 
    unsigned             addr_len;      /**< Length of destination address. */
369
 
    const pj_sockaddr_t *dst_addr;      /**< Destination address.           */
370
 
 
371
 
    pj_timer_entry       res_timer;     /**< Response cache timer.          */
372
 
};
373
 
 
374
 
 
375
 
/**
376
 
 * These are the flags to control the message logging in the STUN session.
377
 
 */
378
 
typedef enum pj_stun_sess_msg_log_flag
379
 
{
380
 
    PJ_STUN_SESS_LOG_TX_REQ=1,  /**< Log outgoing STUN requests.    */
381
 
    PJ_STUN_SESS_LOG_TX_RES=2,  /**< Log outgoing STUN responses.   */
382
 
    PJ_STUN_SESS_LOG_TX_IND=4,  /**< Log outgoing STUN indications. */
383
 
 
384
 
    PJ_STUN_SESS_LOG_RX_REQ=8,  /**< Log incoming STUN requests.    */
385
 
    PJ_STUN_SESS_LOG_RX_RES=16, /**< Log incoming STUN responses    */
386
 
    PJ_STUN_SESS_LOG_RX_IND=32  /**< Log incoming STUN indications  */
387
 
} pj_stun_sess_msg_log_flag;
388
 
 
389
 
 
390
 
/**
391
 
 * Create a STUN session.
392
 
 *
393
 
 * @param cfg           The STUN endpoint, to be used to register timers etc.
394
 
 * @param name          Optional name to be associated with this instance. The
395
 
 *                      name will be used for example for logging purpose.
396
 
 * @param cb            Session callback.
397
 
 * @param fingerprint   Enable message fingerprint for outgoing messages.
398
 
 * @param p_sess        Pointer to receive STUN session instance.
399
 
 *
400
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
401
 
 */
402
 
PJ_DECL(pj_status_t) pj_stun_session_create(pj_stun_config *cfg,
403
 
                                            const char *name,
404
 
                                            const pj_stun_session_cb *cb,
405
 
                                            pj_bool_t fingerprint,
406
 
                                            pj_stun_session **p_sess);
407
 
 
408
 
/**
409
 
 * Destroy the STUN session and all objects created in the context of
410
 
 * this session.
411
 
 *
412
 
 * @param sess      The STUN session instance.
413
 
 *
414
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
415
 
 *                  This function will return PJ_EPENDING if the operation
416
 
 *                  cannot be performed immediately because callbacks are
417
 
 *                  being called; in this case the session will be destroyed
418
 
 *                  as soon as the last callback returns.
419
 
 */
420
 
PJ_DECL(pj_status_t) pj_stun_session_destroy(pj_stun_session *sess);
421
 
 
422
 
/**
423
 
 * Associated an arbitrary data with this STUN session. The user data may
424
 
 * be retrieved later with pj_stun_session_get_user_data() function.
425
 
 *
426
 
 * @param sess      The STUN session instance.
427
 
 * @param user_data The user data.
428
 
 *
429
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
430
 
 */
431
 
PJ_DECL(pj_status_t) pj_stun_session_set_user_data(pj_stun_session *sess,
432
 
                                                   void *user_data);
433
 
 
434
 
/**
435
 
 * Retrieve the user data previously associated to this STUN session with
436
 
 * pj_stun_session_set_user_data().
437
 
 *
438
 
 * @param sess      The STUN session instance.
439
 
 *
440
 
 * @return          The user data associated with this STUN session.
441
 
 */
442
 
PJ_DECL(void*) pj_stun_session_get_user_data(pj_stun_session *sess);
443
 
 
444
 
/**
445
 
 * Change the lock object used by the STUN session. By default, the STUN
446
 
 * session uses a mutex to protect its internal data. If application already
447
 
 * protects access to STUN session with higher layer lock, it may disable
448
 
 * the mutex protection in the STUN session by changing the STUN session
449
 
 * lock to a NULL mutex.
450
 
 *
451
 
 * @param sess      The STUN session instance.
452
 
 * @param lock      New lock instance to be used by the STUN session.
453
 
 * @param auto_del  Specify whether STUN session should destroy this
454
 
 *                  lock instance when it's destroyed.
455
 
 */
456
 
PJ_DECL(pj_status_t) pj_stun_session_set_lock(pj_stun_session *sess,
457
 
                                              pj_lock_t *lock,
458
 
                                              pj_bool_t auto_del);
459
 
 
460
 
/**
461
 
 * Set SOFTWARE name to be included in all requests and responses.
462
 
 *
463
 
 * @param sess      The STUN session instance.
464
 
 * @param sw        Software name string. If this argument is NULL or
465
 
 *                  empty, the session will not include SOFTWARE attribute
466
 
 *                  in STUN requests and responses.
467
 
 *
468
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
469
 
 */
470
 
PJ_DECL(pj_status_t) pj_stun_session_set_software_name(pj_stun_session *sess,
471
 
                                                       const pj_str_t *sw);
472
 
 
473
 
/**
474
 
 * Set credential to be used by this session. Once credential is set, all
475
 
 * outgoing messages will include MESSAGE-INTEGRITY, and all incoming
476
 
 * message will be authenticated against this credential.
477
 
 *
478
 
 * To disable authentication after it has been set, call this function
479
 
 * again with NULL as the argument.
480
 
 *
481
 
 * @param sess      The STUN session instance.
482
 
 * @param auth_type Type of authentication.
483
 
 * @param cred      The credential to be used by this session. If NULL
484
 
 *                  is specified, authentication will be disabled.
485
 
 *
486
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
487
 
 */
488
 
PJ_DECL(pj_status_t) pj_stun_session_set_credential(pj_stun_session *sess,
489
 
                                                pj_stun_auth_type auth_type,
490
 
                                                const pj_stun_auth_cred *cred);
491
 
/**
492
 
 * Configure message logging. By default all flags are enabled.
493
 
 *
494
 
 * @param sess      The STUN session instance.
495
 
 * @param flags     Bitmask combination of #pj_stun_sess_msg_log_flag
496
 
 */
497
 
PJ_DECL(void) pj_stun_session_set_log(pj_stun_session *sess,
498
 
                                      unsigned flags);
499
 
/**
500
 
 * Configure whether the STUN session should utilize FINGERPRINT in
501
 
 * outgoing messages.
502
 
 *
503
 
 * @param sess      The STUN session instance.
504
 
 * @param use       Boolean for the setting.
505
 
 *
506
 
 * @return          The previous configured value of FINGERPRINT
507
 
 *                  utilization of the sessoin.
508
 
 */
509
 
PJ_DECL(pj_bool_t) pj_stun_session_use_fingerprint(pj_stun_session *sess,
510
 
                                                   pj_bool_t use);
511
 
 
512
 
/**
513
 
 * Create a STUN request message. After the message has been successfully
514
 
 * created, application can send the message by calling 
515
 
 * pj_stun_session_send_msg().
516
 
 *
517
 
 * @param sess      The STUN session instance.
518
 
 * @param msg_type  The STUN request message type, from pj_stun_method_e or
519
 
 *                  from pj_stun_msg_type.
520
 
 * @param magic     STUN magic, use PJ_STUN_MAGIC.
521
 
 * @param tsx_id    Optional transaction ID.
522
 
 * @param p_tdata   Pointer to receive STUN transmit data instance containing
523
 
 *                  the request.
524
 
 *
525
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
526
 
 */
527
 
PJ_DECL(pj_status_t) pj_stun_session_create_req(pj_stun_session *sess,
528
 
                                                int msg_type,
529
 
                                                pj_uint32_t magic,
530
 
                                                const pj_uint8_t tsx_id[12],
531
 
                                                pj_stun_tx_data **p_tdata);
532
 
 
533
 
/**
534
 
 * Create a STUN Indication message. After the message  has been successfully
535
 
 * created, application can send the message by calling 
536
 
 * pj_stun_session_send_msg().
537
 
 *
538
 
 * @param sess      The STUN session instance.
539
 
 * @param msg_type  The STUN request message type, from pj_stun_method_e or
540
 
 *                  from pj_stun_msg_type. This function will add the
541
 
 *                  indication bit as necessary.
542
 
 * @param p_tdata   Pointer to receive STUN transmit data instance containing
543
 
 *                  the message.
544
 
 *
545
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
546
 
 */
547
 
PJ_DECL(pj_status_t) pj_stun_session_create_ind(pj_stun_session *sess,
548
 
                                                int msg_type,
549
 
                                                pj_stun_tx_data **p_tdata);
550
 
 
551
 
/**
552
 
 * Create a STUN response message. After the message has been 
553
 
 * successfully created, application can send the message by calling 
554
 
 * pj_stun_session_send_msg(). Alternatively application may use
555
 
 * pj_stun_session_respond() to create and send response in one function
556
 
 * call.
557
 
 *
558
 
 * @param sess      The STUN session instance.
559
 
 * @param rdata     The STUN request where the response is to be created.
560
 
 * @param err_code  Error code to be set in the response, if error response
561
 
 *                  is to be created, according to pj_stun_status enumeration.
562
 
 *                  This argument MUST be zero if successful response is
563
 
 *                  to be created.
564
 
 * @param err_msg   Optional pointer for the error message string, when
565
 
 *                  creating error response. If the value is NULL and the
566
 
 *                  \a err_code is non-zero, then default error message will
567
 
 *                  be used.
568
 
 * @param p_tdata   Pointer to receive the response message created.
569
 
 *
570
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
571
 
 */
572
 
PJ_DECL(pj_status_t) pj_stun_session_create_res(pj_stun_session *sess,
573
 
                                                const pj_stun_rx_data *rdata,
574
 
                                                unsigned err_code,
575
 
                                                const pj_str_t *err_msg,
576
 
                                                pj_stun_tx_data **p_tdata);
577
 
 
578
 
/**
579
 
 * Send STUN message to the specified destination. This function will encode
580
 
 * the pj_stun_msg instance to a packet buffer, and add credential or
581
 
 * fingerprint if necessary. If the message is a request, the session will
582
 
 * also create and manage a STUN client transaction to be used to manage the
583
 
 * retransmission of the request. After the message has been encoded and
584
 
 * transaction is setup, the \a on_send_msg() callback of pj_stun_session_cb
585
 
 * (which is registered when the STUN session is created) will be called
586
 
 * to actually send the message to the wire.
587
 
 *
588
 
 * @param sess      The STUN session instance.
589
 
 * @param token     Optional token which will be given back to application in
590
 
 *                  \a on_send_msg() callback and \a on_request_complete()
591
 
 *                  callback, if the message is a STUN request message. 
592
 
 *                  Internally this function will put the token in the 
593
 
 *                  \a token field of pj_stun_tx_data, hence it will
594
 
 *                  overwrite any value that the application puts there.
595
 
 * @param cache_res If the message is a response message for an incoming
596
 
 *                  request, specify PJ_TRUE to instruct the STUN session
597
 
 *                  to cache this response for subsequent incoming request
598
 
 *                  retransmission. Otherwise this parameter will be ignored
599
 
 *                  for non-response message.
600
 
 * @param retransmit If the message is a request message, specify whether the
601
 
 *                  request should be retransmitted. Normally application will
602
 
 *                  specify TRUE if the underlying transport is UDP and FALSE
603
 
 *                  if the underlying transport is TCP or TLS.
604
 
 * @param dst_addr  The destination socket address.
605
 
 * @param addr_len  Length of destination address.
606
 
 * @param tdata     The STUN transmit data containing the STUN message to
607
 
 *                  be sent.
608
 
 *
609
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
610
 
 *                  This function will return PJNATH_ESTUNDESTROYED if 
611
 
 *                  application has destroyed the session in 
612
 
 *                  \a on_send_msg() callback.
613
 
 */
614
 
PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess,
615
 
                                              void *token,
616
 
                                              pj_bool_t cache_res,
617
 
                                              pj_bool_t retransmit,
618
 
                                              const pj_sockaddr_t *dst_addr,
619
 
                                              unsigned addr_len,
620
 
                                              pj_stun_tx_data *tdata);
621
 
 
622
 
/**
623
 
 * This is a utility function to create and send response for an incoming
624
 
 * STUN request. Internally this function calls pj_stun_session_create_res()
625
 
 * and pj_stun_session_send_msg(). It is provided here as a matter of
626
 
 * convenience.
627
 
 *
628
 
 * @param sess      The STUN session instance.
629
 
 * @param rdata     The STUN request message to be responded.
630
 
 * @param code      Error code to be set in the response, if error response
631
 
 *                  is to be created, according to pj_stun_status enumeration.
632
 
 *                  This argument MUST be zero if successful response is
633
 
 *                  to be created.
634
 
 * @param err_msg   Optional pointer for the error message string, when
635
 
 *                  creating error response. If the value is NULL and the
636
 
 *                  \a err_code is non-zero, then default error message will
637
 
 *                  be used.
638
 
 * @param token     Optional token which will be given back to application in
639
 
 *                  \a on_send_msg() callback and \a on_request_complete()
640
 
 *                  callback, if the message is a STUN request message. 
641
 
 *                  Internally this function will put the token in the 
642
 
 *                  \a token field of pj_stun_tx_data, hence it will
643
 
 *                  overwrite any value that the application puts there.
644
 
 * @param cache     Specify whether session should cache this response for
645
 
 *                  future request retransmission. If TRUE, subsequent request
646
 
 *                  retransmission will be handled by the session and it 
647
 
 *                  will not call request callback.
648
 
 * @param dst_addr  Destination address of the response (or equal to the
649
 
 *                  source address of the original request).
650
 
 * @param addr_len  Address length.
651
 
 *
652
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
653
 
 *                  This function will return PJNATH_ESTUNDESTROYED if 
654
 
 *                  application has destroyed the session in 
655
 
 *                  \a on_send_msg() callback.
656
 
 */
657
 
PJ_DECL(pj_status_t) pj_stun_session_respond(pj_stun_session *sess, 
658
 
                                             const pj_stun_rx_data *rdata,
659
 
                                             unsigned code, 
660
 
                                             const char *err_msg,
661
 
                                             void *token,
662
 
                                             pj_bool_t cache, 
663
 
                                             const pj_sockaddr_t *dst_addr, 
664
 
                                             unsigned addr_len);
665
 
 
666
 
/**
667
 
 * Cancel outgoing STUN transaction. This operation is only valid for outgoing
668
 
 * STUN request, to cease retransmission of the request and destroy the
669
 
 * STUN client transaction that is used to send the request.
670
 
 *
671
 
 * @param sess      The STUN session instance.
672
 
 * @param tdata     The request message previously sent.
673
 
 * @param notify    Specify whether \a on_request_complete() callback should
674
 
 *                  be called.
675
 
 * @param status    If \a on_request_complete() callback is to be called,
676
 
 *                  specify the error status to be given when calling the
677
 
 *                  callback. This error status MUST NOT be PJ_SUCCESS.
678
 
 *
679
 
 * @return          PJ_SUCCESS if transaction is successfully cancelled.
680
 
 *                  This function will return PJNATH_ESTUNDESTROYED if 
681
 
 *                  application has destroyed the session in 
682
 
 *                  \a on_request_complete() callback.
683
 
 */
684
 
PJ_DECL(pj_status_t) pj_stun_session_cancel_req(pj_stun_session *sess,
685
 
                                                pj_stun_tx_data *tdata,
686
 
                                                pj_bool_t notify,
687
 
                                                pj_status_t status);
688
 
 
689
 
/**
690
 
 * Explicitly request retransmission of the request. Normally application
691
 
 * doesn't need to do this, but this functionality is needed by ICE to
692
 
 * speed up connectivity check completion.
693
 
 *
694
 
 * @param sess      The STUN session instance.
695
 
 * @param tdata     The request message previously sent.
696
 
 *
697
 
 * @return          PJ_SUCCESS on success, or the appropriate error.
698
 
 *                  This function will return PJNATH_ESTUNDESTROYED if 
699
 
 *                  application has destroyed the session in \a on_send_msg()
700
 
 *                  callback.
701
 
 */
702
 
PJ_DECL(pj_status_t) pj_stun_session_retransmit_req(pj_stun_session *sess,
703
 
                                                    pj_stun_tx_data *tdata);
704
 
 
705
 
 
706
 
/**
707
 
 * Application must call this function to notify the STUN session about
708
 
 * the arrival of STUN packet. The STUN packet MUST have been checked
709
 
 * first with #pj_stun_msg_check() to verify that this is indeed a valid
710
 
 * STUN packet.
711
 
 *
712
 
 * The STUN session will decode the packet into pj_stun_msg, and process
713
 
 * the message accordingly. If the message is a response, it will search
714
 
 * through the outstanding STUN client transactions for a matching
715
 
 * transaction ID and hand over the response to the transaction.
716
 
 *
717
 
 * On successful message processing, application will be notified about
718
 
 * the message via one of the pj_stun_session_cb callback.
719
 
 *
720
 
 * @param sess          The STUN session instance.
721
 
 * @param packet        The packet containing STUN message.
722
 
 * @param pkt_size      Size of the packet.
723
 
 * @param options       Options, from #pj_stun_decode_options.
724
 
 * @param parsed_len    Optional pointer to receive the size of the parsed
725
 
 *                      STUN message (useful if packet is received via a
726
 
 *                      stream oriented protocol).
727
 
 * @param token         Optional token which will be given back to application
728
 
 *                      in the \a on_rx_request(), \a on_rx_indication() and 
729
 
 *                      \a on_send_msg() callbacks. The token can be used to 
730
 
 *                      associate processing or incoming request or indication
731
 
 *                      with some context.
732
 
 * @param src_addr      The source address of the packet, which will also
733
 
 *                      be given back to application callbacks, along with
734
 
 *                      source address length.
735
 
 * @param src_addr_len  Length of the source address.
736
 
 *
737
 
 * @return              PJ_SUCCESS on success, or the appropriate error code.
738
 
 *                      This function will return PJNATH_ESTUNDESTROYED if 
739
 
 *                      application has destroyed the session in one of the
740
 
 *                      callback.
741
 
 */
742
 
PJ_DECL(pj_status_t) pj_stun_session_on_rx_pkt(pj_stun_session *sess,
743
 
                                               const void *packet,
744
 
                                               pj_size_t pkt_size,
745
 
                                               unsigned options,
746
 
                                               void *token,
747
 
                                               pj_size_t *parsed_len,
748
 
                                               const pj_sockaddr_t *src_addr,
749
 
                                               unsigned src_addr_len);
750
 
 
751
 
/**
752
 
 * Destroy the transmit data. Call this function only when tdata has been
753
 
 * created but application doesn't want to send the message (perhaps
754
 
 * because of other error).
755
 
 *
756
 
 * @param sess      The STUN session.
757
 
 * @param tdata     The transmit data.
758
 
 *
759
 
 * @return          PJ_SUCCESS on success, or the appropriate error code.
760
 
 */
761
 
PJ_DECL(void) pj_stun_msg_destroy_tdata(pj_stun_session *sess,
762
 
                                        pj_stun_tx_data *tdata);
763
 
 
764
 
 
765
 
/**
766
 
 * @}
767
 
 */
768
 
 
769
 
 
770
 
PJ_END_DECL
771
 
 
772
 
#endif  /* __PJNATH_STUN_SESSION_H__ */
773