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_grp_lock_t *grp_lock; /**< Group lock (for resp cache). */ 353 354 pj_stun_req_cred_info auth_info; /**< Credential info */ 355 356 void *pkt; /**< The STUN packet. */ 357 unsigned max_len; /**< Length of packet buffer. */ 358 pj_size_t pkt_size; /**< The actual length of STUN pkt. */ 359 360 unsigned addr_len; /**< Length of destination address. */ 361 const pj_sockaddr_t *dst_addr; /**< Destination address. */ 362 363 pj_timer_entry res_timer; /**< Response cache timer. */ 364 }; 365 366 367 /** 368 * These are the flags to control the message logging in the STUN session. 369 */ 370 typedef enum pj_stun_sess_msg_log_flag 371 { 372 PJ_STUN_SESS_LOG_TX_REQ=1, /**< Log outgoing STUN requests. */ 373 PJ_STUN_SESS_LOG_TX_RES=2, /**< Log outgoing STUN responses. */ 374 PJ_STUN_SESS_LOG_TX_IND=4, /**< Log outgoing STUN indications. */ 375 376 PJ_STUN_SESS_LOG_RX_REQ=8, /**< Log incoming STUN requests. */ 377 PJ_STUN_SESS_LOG_RX_RES=16, /**< Log incoming STUN responses */ 378 PJ_STUN_SESS_LOG_RX_IND=32 /**< Log incoming STUN indications */ 379 } pj_stun_sess_msg_log_flag; 380 381 382 /** 383 * Create a STUN session. 384 * 385 * @param cfg The STUN endpoint, to be used to register timers etc. 386 * @param name Optional name to be associated with this instance. The 387 * name will be used for example for logging purpose. 388 * @param cb Session callback. 389 * @param fingerprint Enable message fingerprint for outgoing messages. 390 * @param grp_lock Optional group lock to be used by this session. 391 * If NULL, the session will create one itself. 392 * @param p_sess Pointer to receive STUN session instance. 393 * 394 * @return PJ_SUCCESS on success, or the appropriate error code. 395 */ 396 PJ_DECL(pj_status_t) pj_stun_session_create(pj_stun_config *cfg, 397 const char *name, 398 const pj_stun_session_cb *cb, 399 pj_bool_t fingerprint, 400 pj_grp_lock_t *grp_lock, 401 pj_stun_session **p_sess); 402 403 /** 404 * Destroy the STUN session and all objects created in the context of 405 * this session. 406 * 407 * @param sess The STUN session instance. 408 * 409 * @return PJ_SUCCESS on success, or the appropriate error code. 410 * This function will return PJ_EPENDING if the operation 411 * cannot be performed immediately because callbacks are 412 * being called; in this case the session will be destroyed 413 * as soon as the last callback returns. 414 */ 415 PJ_DECL(pj_status_t) pj_stun_session_destroy(pj_stun_session *sess); 416 417 /** 418 * Associated an arbitrary data with this STUN session. The user data may 419 * be retrieved later with pj_stun_session_get_user_data() function. 420 * 421 * @param sess The STUN session instance. 422 * @param user_data The user data. 423 * 424 * @return PJ_SUCCESS on success, or the appropriate error code. 425 */ 426 PJ_DECL(pj_status_t) pj_stun_session_set_user_data(pj_stun_session *sess, 427 void *user_data); 428 429 /** 430 * Retrieve the user data previously associated to this STUN session with 431 * pj_stun_session_set_user_data(). 432 * 433 * @param sess The STUN session instance. 434 * 435 * @return The user data associated with this STUN session. 436 */ 437 PJ_DECL(void*) pj_stun_session_get_user_data(pj_stun_session *sess); 438 439 /** 440 * Get the group lock for this STUN session. 441 * 442 * @param sess The STUN session instance. 443 * 444 * @return The group lock. 445 */ 446 PJ_DECL(pj_grp_lock_t *) pj_stun_session_get_grp_lock(pj_stun_session *sess); 447 448 /** 449 * Set SOFTWARE name to be included in all requests and responses. 450 * 451 * @param sess The STUN session instance. 452 * @param sw Software name string. If this argument is NULL or 453 * empty, the session will not include SOFTWARE attribute 454 * in STUN requests and responses. 455 * 456 * @return PJ_SUCCESS on success, or the appropriate error code. 457 */ 458 PJ_DECL(pj_status_t) pj_stun_session_set_software_name(pj_stun_session *sess, 459 const pj_str_t *sw); 460 461 /** 462 * Set credential to be used by this session. Once credential is set, all 463 * outgoing messages will include MESSAGE-INTEGRITY, and all incoming 464 * message will be authenticated against this credential. 465 * 466 * To disable authentication after it has been set, call this function 467 * again with NULL as the argument. 468 * 469 * @param sess The STUN session instance. 470 * @param auth_type Type of authentication. 471 * @param cred The credential to be used by this session. If NULL 472 * is specified, authentication will be disabled. 473 * 474 * @return PJ_SUCCESS on success, or the appropriate error code. 475 */ 476 PJ_DECL(pj_status_t) pj_stun_session_set_credential(pj_stun_session *sess, 477 pj_stun_auth_type auth_type, 478 const pj_stun_auth_cred *cred); 479 /** 480 * Configure message logging. By default all flags are enabled. 481 * 482 * @param sess The STUN session instance. 483 * @param flags Bitmask combination of #pj_stun_sess_msg_log_flag 484 */ 485 PJ_DECL(void) pj_stun_session_set_log(pj_stun_session *sess, 486 unsigned flags); 487 /** 488 * Configure whether the STUN session should utilize FINGERPRINT in 489 * outgoing messages. 490 * 491 * @param sess The STUN session instance. 492 * @param use Boolean for the setting. 493 * 494 * @return The previous configured value of FINGERPRINT 495 * utilization of the sessoin. 496 */ 497 PJ_DECL(pj_bool_t) pj_stun_session_use_fingerprint(pj_stun_session *sess, 498 pj_bool_t use); 499 500 /** 501 * Create a STUN request message. After the message has been successfully 502 * created, application can send the message by calling 503 * pj_stun_session_send_msg(). 504 * 505 * @param sess The STUN session instance. 506 * @param msg_type The STUN request message type, from pj_stun_method_e or 507 * from pj_stun_msg_type. 508 * @param magic STUN magic, use PJ_STUN_MAGIC. 509 * @param tsx_id Optional transaction ID. 510 * @param p_tdata Pointer to receive STUN transmit data instance containing 511 * the request. 512 * 513 * @return PJ_SUCCESS on success, or the appropriate error code. 514 */ 515 PJ_DECL(pj_status_t) pj_stun_session_create_req(pj_stun_session *sess, 516 int msg_type, 517 pj_uint32_t magic, 518 const pj_uint8_t tsx_id[12], 519 pj_stun_tx_data **p_tdata); 520 521 /** 522 * Create a STUN Indication message. After the message has been successfully 523 * created, application can send the message by calling 524 * pj_stun_session_send_msg(). 525 * 526 * @param sess The STUN session instance. 527 * @param msg_type The STUN request message type, from pj_stun_method_e or 528 * from pj_stun_msg_type. This function will add the 529 * indication bit as necessary. 530 * @param p_tdata Pointer to receive STUN transmit data instance containing 531 * the message. 532 * 533 * @return PJ_SUCCESS on success, or the appropriate error code. 534 */ 535 PJ_DECL(pj_status_t) pj_stun_session_create_ind(pj_stun_session *sess, 536 int msg_type, 537 pj_stun_tx_data **p_tdata); 538 539 /** 540 * Create a STUN response message. After the message has been 541 * successfully created, application can send the message by calling 542 * pj_stun_session_send_msg(). Alternatively application may use 543 * pj_stun_session_respond() to create and send response in one function 544 * call. 545 * 546 * @param sess The STUN session instance. 547 * @param rdata The STUN request where the response is to be created. 548 * @param err_code Error code to be set in the response, if error response 549 * is to be created, according to pj_stun_status enumeration. 550 * This argument MUST be zero if successful response is 551 * to be created. 552 * @param err_msg Optional pointer for the error message string, when 553 * creating error response. If the value is NULL and the 554 * \a err_code is non-zero, then default error message will 555 * be used. 556 * @param p_tdata Pointer to receive the response message created. 557 * 558 * @return PJ_SUCCESS on success, or the appropriate error code. 559 */ 560 PJ_DECL(pj_status_t) pj_stun_session_create_res(pj_stun_session *sess, 561 const pj_stun_rx_data *rdata, 562 unsigned err_code, 563 const pj_str_t *err_msg, 564 pj_stun_tx_data **p_tdata); 565 566 /** 567 * Send STUN message to the specified destination. This function will encode 568 * the pj_stun_msg instance to a packet buffer, and add credential or 569 * fingerprint if necessary. If the message is a request, the session will 570 * also create and manage a STUN client transaction to be used to manage the 571 * retransmission of the request. After the message has been encoded and 572 * transaction is setup, the \a on_send_msg() callback of pj_stun_session_cb 573 * (which is registered when the STUN session is created) will be called 574 * to actually send the message to the wire. 575 * 576 * @param sess The STUN session instance. 577 * @param token Optional token which will be given back to application in 578 * \a on_send_msg() callback and \a on_request_complete() 579 * callback, if the message is a STUN request message. 580 * Internally this function will put the token in the 581 * \a token field of pj_stun_tx_data, hence it will 582 * overwrite any value that the application puts there. 583 * @param cache_res If the message is a response message for an incoming 584 * request, specify PJ_TRUE to instruct the STUN session 585 * to cache this response for subsequent incoming request 586 * retransmission. Otherwise this parameter will be ignored 587 * for non-response message. 588 * @param retransmit If the message is a request message, specify whether the 589 * request should be retransmitted. Normally application will 590 * specify TRUE if the underlying transport is UDP and FALSE 591 * if the underlying transport is TCP or TLS. 592 * @param dst_addr The destination socket address. 593 * @param addr_len Length of destination address. 594 * @param tdata The STUN transmit data containing the STUN message to 595 * be sent. 596 * 597 * @return PJ_SUCCESS on success, or the appropriate error code. 598 * This function will return PJNATH_ESTUNDESTROYED if 599 * application has destroyed the session in 600 * \a on_send_msg() callback. 601 */ 602 PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess, 603 void *token, 604 pj_bool_t cache_res, 605 pj_bool_t retransmit, 606 const pj_sockaddr_t *dst_addr, 607 unsigned addr_len, 608 pj_stun_tx_data *tdata); 609 610 /** 611 * This is a utility function to create and send response for an incoming 612 * STUN request. Internally this function calls pj_stun_session_create_res() 613 * and pj_stun_session_send_msg(). It is provided here as a matter of 614 * convenience. 615 * 616 * @param sess The STUN session instance. 617 * @param rdata The STUN request message to be responded. 618 * @param code Error code to be set in the response, if error response 619 * is to be created, according to pj_stun_status enumeration. 620 * This argument MUST be zero if successful response is 621 * to be created. 622 * @param err_msg Optional pointer for the error message string, when 623 * creating error response. If the value is NULL and the 624 * \a err_code is non-zero, then default error message will 625 * be used. 626 * @param token Optional token which will be given back to application in 627 * \a on_send_msg() callback and \a on_request_complete() 628 * callback, if the message is a STUN request message. 629 * Internally this function will put the token in the 630 * \a token field of pj_stun_tx_data, hence it will 631 * overwrite any value that the application puts there. 632 * @param cache Specify whether session should cache this response for 633 * future request retransmission. If TRUE, subsequent request 634 * retransmission will be handled by the session and it 635 * will not call request callback. 636 * @param dst_addr Destination address of the response (or equal to the 637 * source address of the original request). 638 * @param addr_len Address length. 639 * 640 * @return PJ_SUCCESS on success, or the appropriate error code. 641 * This function will return PJNATH_ESTUNDESTROYED if 642 * application has destroyed the session in 643 * \a on_send_msg() callback. 644 */ 645 PJ_DECL(pj_status_t) pj_stun_session_respond(pj_stun_session *sess, 646 const pj_stun_rx_data *rdata, 647 unsigned code, 648 const char *err_msg, 649 void *token, 650 pj_bool_t cache, 651 const pj_sockaddr_t *dst_addr, 652 unsigned addr_len); 653 654 /** 655 * Cancel outgoing STUN transaction. This operation is only valid for outgoing 656 * STUN request, to cease retransmission of the request and destroy the 657 * STUN client transaction that is used to send the request. 658 * 659 * @param sess The STUN session instance. 660 * @param tdata The request message previously sent. 661 * @param notify Specify whether \a on_request_complete() callback should 662 * be called. 663 * @param status If \a on_request_complete() callback is to be called, 664 * specify the error status to be given when calling the 665 * callback. This error status MUST NOT be PJ_SUCCESS. 666 * 667 * @return PJ_SUCCESS if transaction is successfully cancelled. 668 * This function will return PJNATH_ESTUNDESTROYED if 669 * application has destroyed the session in 670 * \a on_request_complete() callback. 671 */ 672 PJ_DECL(pj_status_t) pj_stun_session_cancel_req(pj_stun_session *sess, 673 pj_stun_tx_data *tdata, 674 pj_bool_t notify, 675 pj_status_t status); 676 677 /** 678 * Explicitly request retransmission of the request. Normally application 679 * doesn't need to do this, but this functionality is needed by ICE to 680 * speed up connectivity check completion. 681 * 682 * @param sess The STUN session instance. 683 * @param tdata The request message previously sent. 684 * @param mod_count Boolean flag to indicate whether transmission count 685 * needs to be incremented. 686 * 687 * @return PJ_SUCCESS on success, or the appropriate error. 688 * This function will return PJNATH_ESTUNDESTROYED if 689 * application has destroyed the session in \a on_send_msg() 690 * callback. 691 */ 692 PJ_DECL(pj_status_t) pj_stun_session_retransmit_req(pj_stun_session *sess, 693 pj_stun_tx_data *tdata, 694 pj_bool_t mod_count); 695 696 697 /** 698 * Application must call this function to notify the STUN session about 699 * the arrival of STUN packet. The STUN packet MUST have been checked 700 * first with #pj_stun_msg_check() to verify that this is indeed a valid 701 * STUN packet. 702 * 703 * The STUN session will decode the packet into pj_stun_msg, and process 704 * the message accordingly. If the message is a response, it will search 705 * through the outstanding STUN client transactions for a matching 706 * transaction ID and hand over the response to the transaction. 707 * 708 * On successful message processing, application will be notified about 709 * the message via one of the pj_stun_session_cb callback. 710 * 711 * @param sess The STUN session instance. 712 * @param packet The packet containing STUN message. 713 * @param pkt_size Size of the packet. 714 * @param options Options, from #pj_stun_decode_options. 715 * @param parsed_len Optional pointer to receive the size of the parsed 716 * STUN message (useful if packet is received via a 717 * stream oriented protocol). 718 * @param token Optional token which will be given back to application 719 * in the \a on_rx_request(), \a on_rx_indication() and 720 * \a on_send_msg() callbacks. The token can be used to 721 * associate processing or incoming request or indication 722 * with some context. 723 * @param src_addr The source address of the packet, which will also 724 * be given back to application callbacks, along with 725 * source address length. 726 * @param src_addr_len Length of the source address. 727 * 728 * @return PJ_SUCCESS on success, or the appropriate error code. 729 * This function will return PJNATH_ESTUNDESTROYED if 730 * application has destroyed the session in one of the 731 * callback. 732 */ 733 PJ_DECL(pj_status_t) pj_stun_session_on_rx_pkt(pj_stun_session *sess, 734 const void *packet, 735 pj_size_t pkt_size, 736 unsigned options, 737 void *token, 738 pj_size_t *parsed_len, 739 const pj_sockaddr_t *src_addr, 740 unsigned src_addr_len); 741 742 /** 743 * Destroy the transmit data. Call this function only when tdata has been 744 * created but application doesn't want to send the message (perhaps 745 * because of other error). 746 * 747 * @param sess The STUN session. 748 * @param tdata The transmit data. 749 * 750 * @return PJ_SUCCESS on success, or the appropriate error code. 751 */ 752 PJ_DECL(void) pj_stun_msg_destroy_tdata(pj_stun_session *sess, 753 pj_stun_tx_data *tdata); 754 755 756 /** 757 * @} 758 */ 759 760 761 PJ_END_DECL 762 763 #endif /* __PJNATH_STUN_SESSION_H__ */ 764 765