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