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