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_TURN_SESSION_H__ |
| 21 | #define __PJNATH_TURN_SESSION_H__ |
| 22 | |
| 23 | /** |
| 24 | * @file turn_session.h |
| 25 | * @brief Transport independent TURN client session. |
| 26 | */ |
| 27 | #include <pjnath/stun_session.h> |
| 28 | #include <pjlib-util/resolver.h> |
| 29 | |
| 30 | |
| 31 | PJ_BEGIN_DECL |
| 32 | |
| 33 | |
| 34 | /* **************************************************************************/ |
| 35 | /** |
| 36 | @addtogroup PJNATH_TURN_SESSION |
| 37 | @{ |
| 38 | |
| 39 | The \ref PJNATH_TURN_SESSION is a transport-independent object to |
| 40 | manage a client TURN session. It contains the core logic for manage |
| 41 | the TURN client session as listed in \ref turn_op_sec, but |
| 42 | in transport-independent manner (i.e. it doesn't have a socket), so |
| 43 | that developer can integrate TURN client functionality into existing |
| 44 | framework that already has its own means to send and receive data, |
| 45 | or to support new transport types to TURN, such as TLS. |
| 46 | |
| 47 | |
| 48 | \section turn_sess_using_sec Using the TURN session |
| 49 | |
| 50 | These steps describes how to use the TURN session: |
| 51 | |
| 52 | - <b>Creating the session</b>:\n |
| 53 | use #pj_turn_session_create() to create the session. |
| 54 | |
| 55 | - <b>Configuring credential</b>:\n |
| 56 | all TURN operations requires the use of authentication (it uses STUN |
| 57 | long term autentication method). Use #pj_turn_session_set_credential() |
| 58 | to configure the TURN credential to be used by the session. |
| 59 | |
| 60 | - <b>Configuring server</b>:\n |
| 61 | application must call #pj_turn_session_set_server() before it can send |
| 62 | Allocate request (with pj_turn_session_alloc()). This function will |
| 63 | resolve the TURN server using DNS SRV resolution if the \a resolver |
| 64 | is set. The server resolution process will complete asynchronously, |
| 65 | and application will be notified in \a on_state() callback of the |
| 66 | #pj_turn_session_cb structurewith the session state set to |
| 67 | PJ_TURN_STATE_RESOLVED. |
| 68 | |
| 69 | - <b>Creating allocation</b>:\n |
| 70 | create one "relay port" (or called <b>relayed-transport-address</b> |
| 71 | in TURN terminology) in the TURN server by using #pj_turn_session_alloc(). |
| 72 | This will send Allocate request to the server. This function will complete |
| 73 | immediately, and application will be notified about the allocation |
| 74 | result in the \a on_state() callback of the #pj_turn_session_cb structure. |
| 75 | |
| 76 | - <b>Getting the allocation result</b>:\n |
| 77 | if allocation is successful, the session state will progress to |
| 78 | \a PJ_TURN_STATE_READY, otherwise the state will be |
| 79 | \a PJ_TURN_STATE_DEALLOCATED or higher. Session state progression is |
| 80 | reported in the \a on_state() callback of the #pj_turn_session_cb |
| 81 | structure. On successful allocation, application may retrieve the |
| 82 | allocation info by calling #pj_turn_session_get_info(). |
| 83 | |
| 84 | - <b>Sending data through the relay</b>.\n |
| 85 | Once allocation has been created, client may send data to any remote |
| 86 | endpoints (called peers in TURN terminology) via the "relay port". It does |
| 87 | so by calling #pj_turn_session_sendto(), giving the peer address |
| 88 | in the function argument. But note that at this point peers are not allowed |
| 89 | to send data towards the client (via the "relay port") before permission is |
| 90 | installed for that peer. |
| 91 | |
| 92 | - <b>Creating permissions</b>.\n |
| 93 | Permission needs to be created in the TURN server so that a peer can send |
| 94 | data to the client via the relay port (a peer in this case is identified by |
| 95 | its IP address). Without this, when the TURN server receives data from the |
| 96 | peer in the "relay port", it will drop this data. Create the permission by |
| 97 | calling #pj_turn_session_set_perm(), specifying the peer IP address in the |
| 98 | argument (the port part of the address is ignored). More than one IP |
| 99 | addresses may be specified. |
| 100 | |
| 101 | - <b>Receiving data from peers</b>.\n |
| 102 | Once permission has been installed for the peer, any data received by the |
| 103 | TURN server (from that peer) in the "relay port" will be relayed back to |
| 104 | client by the server, and application will be notified via \a on_rx_data |
| 105 | callback of the #pj_turn_session_cb. |
| 106 | |
| 107 | - <b>Using ChannelData</b>.\n |
| 108 | TURN provides optimized framing to the data by using ChannelData |
| 109 | packetization. The client activates this format for the specified peer by |
| 110 | calling #pj_turn_session_bind_channel(). Data sent or received to/for |
| 111 | this peer will then use ChannelData format instead of Send or Data |
| 112 | Indications. |
| 113 | |
| 114 | - <b>Refreshing the allocation, permissions, and channel bindings</b>.\n |
| 115 | Allocations, permissions, and channel bindings will be refreshed by the |
| 116 | session automatically when they about to expire. |
| 117 | |
| 118 | - <b>Destroying the allocation</b>.\n |
| 119 | Once the "relay port" is no longer needed, client destroys the allocation |
| 120 | by calling #pj_turn_session_shutdown(). This function will return |
| 121 | immediately, and application will be notified about the deallocation |
| 122 | result in the \a on_state() callback of the #pj_turn_session_cb structure. |
| 123 | Once the state has reached PJ_TURN_STATE_DESTROYING, application must |
| 124 | assume that the session will be destroyed shortly after. |
| 125 | |
| 126 | */ |
| 127 | |
| 128 | /** |
| 129 | * Opaque declaration for TURN client session. |
| 130 | */ |
| 131 | typedef struct pj_turn_session pj_turn_session; |
| 132 | |
| 133 | |
| 134 | /** |
| 135 | * TURN transport types, which will be used both to specify the connection |
| 136 | * type for reaching TURN server and the type of allocation transport to be |
| 137 | * requested to server (the REQUESTED-TRANSPORT attribute). |
| 138 | */ |
| 139 | typedef enum pj_turn_tp_type |
| 140 | { |
| 141 | /** |
| 142 | * UDP transport, which value corresponds to IANA protocol number. |
| 143 | */ |
| 144 | PJ_TURN_TP_UDP = 17, |
| 145 | |
| 146 | /** |
| 147 | * TCP transport, which value corresponds to IANA protocol number. |
| 148 | */ |
| 149 | PJ_TURN_TP_TCP = 6, |
| 150 | |
| 151 | /** |
| 152 | * TLS transport. The TLS transport will only be used as the connection |
| 153 | * type to reach the server and never as the allocation transport type. |
| 154 | */ |
| 155 | PJ_TURN_TP_TLS = 255 |
| 156 | |
| 157 | } pj_turn_tp_type; |
| 158 | |
| 159 | |
| 160 | /** TURN session state */ |
| 161 | typedef enum pj_turn_state_t |
| 162 | { |
| 163 | /** |
| 164 | * TURN session has just been created. |
| 165 | */ |
| 166 | PJ_TURN_STATE_NULL, |
| 167 | |
| 168 | /** |
| 169 | * TURN server has been configured and now is being resolved via |
| 170 | * DNS SRV resolution. |
| 171 | */ |
| 172 | PJ_TURN_STATE_RESOLVING, |
| 173 | |
| 174 | /** |
| 175 | * TURN server has been resolved. If there is pending allocation to |
| 176 | * be done, it will be invoked immediately. |
| 177 | */ |
| 178 | PJ_TURN_STATE_RESOLVED, |
| 179 | |
| 180 | /** |
| 181 | * TURN session has issued ALLOCATE request and is waiting for response |
| 182 | * from the TURN server. |
| 183 | */ |
| 184 | PJ_TURN_STATE_ALLOCATING, |
| 185 | |
| 186 | /** |
| 187 | * TURN session has successfully allocated relay resoruce and now is |
| 188 | * ready to be used. |
| 189 | */ |
| 190 | PJ_TURN_STATE_READY, |
| 191 | |
| 192 | /** |
| 193 | * TURN session has issued deallocate request and is waiting for a |
| 194 | * response from the TURN server. |
| 195 | */ |
| 196 | PJ_TURN_STATE_DEALLOCATING, |
| 197 | |
| 198 | /** |
| 199 | * Deallocate response has been received. Normally the session will |
| 200 | * proceed to DESTROYING state immediately. |
| 201 | */ |
| 202 | PJ_TURN_STATE_DEALLOCATED, |
| 203 | |
| 204 | /** |
| 205 | * TURN session is being destroyed. |
| 206 | */ |
| 207 | PJ_TURN_STATE_DESTROYING |
| 208 | |
| 209 | } pj_turn_state_t; |
| 210 | |
| 211 | |
| 212 | #pragma pack(1) |
| 213 | |
| 214 | /** |
| 215 | * This structure ChannelData header. All the fields are in network byte |
| 216 | * order when it's on the wire. |
| 217 | */ |
| 218 | typedef struct pj_turn_channel_data |
| 219 | { |
| 220 | pj_uint16_t ch_number; /**< Channel number. */ |
| 221 | pj_uint16_t length; /**< Payload length. */ |
| 222 | } pj_turn_channel_data; |
| 223 | |
| 224 | |
| 225 | #pragma pack() |
| 226 | |
| 227 | |
| 228 | /** |
| 229 | * Callback to receive events from TURN session. |
| 230 | */ |
| 231 | typedef struct pj_turn_session_cb |
| 232 | { |
| 233 | /** |
| 234 | * This callback will be called by the TURN session whenever it |
| 235 | * needs to send outgoing message. Since the TURN session doesn't |
| 236 | * have a socket on its own, this callback must be implemented. |
| 237 | * |
| 238 | * @param sess The TURN session. |
| 239 | * @param pkt The packet/data to be sent. |
| 240 | * @param pkt_len Length of the packet/data. |
| 241 | * @param dst_addr Destination address of the packet. |
| 242 | * @param addr_len Length of the destination address. |
| 243 | * |
| 244 | * @return The callback should return the status of the |
| 245 | * send operation. |
| 246 | */ |
| 247 | pj_status_t (*on_send_pkt)(pj_turn_session *sess, |
| 248 | const pj_uint8_t *pkt, |
| 249 | unsigned pkt_len, |
| 250 | const pj_sockaddr_t *dst_addr, |
| 251 | unsigned addr_len); |
| 252 | |
| 253 | /** |
| 254 | * Notification when peer address has been bound successfully to |
| 255 | * a channel number. |
| 256 | * |
| 257 | * This callback is optional since the nature of this callback is |
| 258 | * for information only. |
| 259 | * |
| 260 | * @param sess The TURN session. |
| 261 | * @param peer_addr The peer address. |
| 262 | * @param addr_len Length of the peer address. |
| 263 | * @param ch_num The channel number associated with this peer address. |
| 264 | */ |
| 265 | void (*on_channel_bound)(pj_turn_session *sess, |
| 266 | const pj_sockaddr_t *peer_addr, |
| 267 | unsigned addr_len, |
| 268 | unsigned ch_num); |
| 269 | |
| 270 | /** |
| 271 | * Notification when incoming data has been received, either through |
| 272 | * Data indication or ChannelData message from the TURN server. |
| 273 | * |
| 274 | * @param sess The TURN session. |
| 275 | * @param pkt The data/payload of the Data Indication or ChannelData |
| 276 | * packet. |
| 277 | * @param pkt_len Length of the data/payload. |
| 278 | * @param peer_addr Peer address where this payload was received by |
| 279 | * the TURN server. |
| 280 | * @param addr_len Length of the peer address. |
| 281 | */ |
| 282 | void (*on_rx_data)(pj_turn_session *sess, |
| 283 | void *pkt, |
| 284 | unsigned pkt_len, |
| 285 | const pj_sockaddr_t *peer_addr, |
| 286 | unsigned addr_len); |
| 287 | |
| 288 | /** |
| 289 | * Notification when TURN session state has changed. Application should |
| 290 | * implement this callback at least to know that the TURN session is |
| 291 | * going to be destroyed. |
| 292 | * |
| 293 | * @param sess The TURN session. |
| 294 | * @param old_state The previous state of the session. |
| 295 | * @param new_state The current state of the session. |
| 296 | */ |
| 297 | void (*on_state)(pj_turn_session *sess, |
| 298 | pj_turn_state_t old_state, |
| 299 | pj_turn_state_t new_state); |
| 300 | |
| 301 | } pj_turn_session_cb; |
| 302 | |
| 303 | |
| 304 | /** |
| 305 | * Allocation parameter, which can be given when application calls |
| 306 | * pj_turn_session_alloc() to allocate relay address in the TURN server. |
| 307 | * Application should call pj_turn_alloc_param_default() to initialize |
| 308 | * this structure with the default values. |
| 309 | */ |
| 310 | typedef struct pj_turn_alloc_param |
| 311 | { |
| 312 | /** |
| 313 | * The requested BANDWIDTH. Default is zero to not request any |
| 314 | * specific bandwidth. Note that this attribute has been deprecated |
| 315 | * after TURN-08 draft, hence application should only use this |
| 316 | * attribute when talking to TURN-07 or older version. |
| 317 | */ |
| 318 | int bandwidth; |
| 319 | |
| 320 | /** |
| 321 | * The requested LIFETIME. Default is zero to not request any |
| 322 | * explicit allocation lifetime. |
| 323 | */ |
| 324 | int lifetime; |
| 325 | |
| 326 | /** |
| 327 | * If set to non-zero, the TURN session will periodically send blank |
| 328 | * Send Indication every PJ_TURN_KEEP_ALIVE_SEC to refresh local |
| 329 | * NAT bindings. Default is zero. |
| 330 | */ |
| 331 | int ka_interval; |
| 332 | |
| 333 | } pj_turn_alloc_param; |
| 334 | |
| 335 | |
| 336 | /** |
| 337 | * This structure describes TURN session info. |
| 338 | */ |
| 339 | typedef struct pj_turn_session_info |
| 340 | { |
| 341 | /** |
| 342 | * Session state. |
| 343 | */ |
| 344 | pj_turn_state_t state; |
| 345 | |
| 346 | /** |
| 347 | * Last error (if session was terminated because of error) |
| 348 | */ |
| 349 | pj_status_t last_status; |
| 350 | |
| 351 | /** |
| 352 | * Type of connection to the TURN server. |
| 353 | */ |
| 354 | pj_turn_tp_type conn_type; |
| 355 | |
| 356 | /** |
| 357 | * The selected TURN server address. |
| 358 | */ |
| 359 | pj_sockaddr server; |
| 360 | |
| 361 | /** |
| 362 | * Mapped address, as reported by the TURN server. |
| 363 | */ |
| 364 | pj_sockaddr mapped_addr; |
| 365 | |
| 366 | /** |
| 367 | * The relay address |
| 368 | */ |
| 369 | pj_sockaddr relay_addr; |
| 370 | |
| 371 | /** |
| 372 | * Current seconds before allocation expires. |
| 373 | */ |
| 374 | int lifetime; |
| 375 | |
| 376 | } pj_turn_session_info; |
| 377 | |
| 378 | |
| 379 | /** |
| 380 | * Initialize pj_turn_alloc_param with the default values. |
| 381 | * |
| 382 | * @param prm The TURN allocation parameter to be initialized. |
| 383 | */ |
| 384 | PJ_DECL(void) pj_turn_alloc_param_default(pj_turn_alloc_param *prm); |
| 385 | |
| 386 | |
| 387 | /** |
| 388 | * Duplicate pj_turn_alloc_param. |
| 389 | * |
| 390 | * @param pool Pool to allocate memory (currently not used) |
| 391 | * @param dst Destination parameter. |
| 392 | * @param src Source parameter. |
| 393 | */ |
| 394 | PJ_DECL(void) pj_turn_alloc_param_copy(pj_pool_t *pool, |
| 395 | pj_turn_alloc_param *dst, |
| 396 | const pj_turn_alloc_param *src); |
| 397 | |
| 398 | /** |
| 399 | * Get string representation for the given TURN state. |
| 400 | * |
| 401 | * @param state The TURN session state. |
| 402 | * |
| 403 | * @return The state name as NULL terminated string. |
| 404 | */ |
| 405 | PJ_DECL(const char*) pj_turn_state_name(pj_turn_state_t state); |
| 406 | |
| 407 | |
| 408 | /** |
| 409 | * Create a TURN session instance with the specified address family and |
| 410 | * connection type. Once TURN session instance is created, application |
| 411 | * must call pj_turn_session_alloc() to allocate a relay address in the TURN |
| 412 | * server. |
| 413 | * |
| 414 | * @param cfg The STUN configuration which contains among other |
| 415 | * things the ioqueue and timer heap instance for |
| 416 | * the operation of this session. |
| 417 | * @param name Optional name to identify this session in the log. |
| 418 | * @param af Address family of the client connection. Currently |
| 419 | * pj_AF_INET() and pj_AF_INET6() are supported. |
| 420 | * @param conn_type Connection type to the TURN server. |
| 421 | * @param grp_lock Optional group lock object to be used by this session. |
| 422 | * If this value is NULL, the session will create |
| 423 | * a group lock internally. |
| 424 | * @param cb Callback to receive events from the TURN session. |
| 425 | * @param options Option flags, currently this value must be zero. |
| 426 | * @param user_data Arbitrary application data to be associated with |
| 427 | * this transport. |
| 428 | * @param p_sess Pointer to receive the created instance of the |
| 429 | * TURN session. |
| 430 | * |
| 431 | * @return PJ_SUCCESS if the operation has been successful, |
| 432 | * or the appropriate error code on failure. |
| 433 | */ |
| 434 | PJ_DECL(pj_status_t) pj_turn_session_create(const pj_stun_config *cfg, |
| 435 | const char *name, |
| 436 | int af, |
| 437 | pj_turn_tp_type conn_type, |
| 438 | pj_grp_lock_t *grp_lock, |
| 439 | const pj_turn_session_cb *cb, |
| 440 | unsigned options, |
| 441 | void *user_data, |
| 442 | pj_turn_session **p_sess); |
| 443 | |
| 444 | /** |
| 445 | * Shutdown TURN client session. This will gracefully deallocate and |
| 446 | * destroy the client session. |
| 447 | * |
| 448 | * @param sess The TURN client session. |
| 449 | * |
| 450 | * @return PJ_SUCCESS if the operation has been successful, |
| 451 | * or the appropriate error code on failure. |
| 452 | */ |
| 453 | PJ_DECL(pj_status_t) pj_turn_session_shutdown(pj_turn_session *sess); |
| 454 | |
| 455 | |
| 456 | /** |
| 457 | * Forcefully destroy the TURN session. This will destroy the session |
| 458 | * immediately. If there is an active allocation, the server will not |
| 459 | * be notified about the client destruction. |
| 460 | * |
| 461 | * @param sess The TURN client session. |
| 462 | * @param last_err Optional error code to be set to the session, |
| 463 | * which would be returned back in the \a info |
| 464 | * parameter of #pj_turn_session_get_info(). If |
| 465 | * this argument value is PJ_SUCCESS, the error |
| 466 | * code will not be set. If the session already |
| 467 | * has an error code set, this function will not |
| 468 | * overwrite that error code either. |
| 469 | * |
| 470 | * @return PJ_SUCCESS if the operation has been successful, |
| 471 | * or the appropriate error code on failure. |
| 472 | */ |
| 473 | PJ_DECL(pj_status_t) pj_turn_session_destroy(pj_turn_session *sess, |
| 474 | pj_status_t last_err); |
| 475 | |
| 476 | |
| 477 | /** |
| 478 | * Get the information about this TURN session and the allocation, if |
| 479 | * any. |
| 480 | * |
| 481 | * @param sess The TURN client session. |
| 482 | * @param info The structure to be initialized with the TURN |
| 483 | * session info. |
| 484 | * |
| 485 | * @return PJ_SUCCESS if the operation has been successful, |
| 486 | * or the appropriate error code on failure. |
| 487 | */ |
| 488 | PJ_DECL(pj_status_t) pj_turn_session_get_info(pj_turn_session *sess, |
| 489 | pj_turn_session_info *info); |
| 490 | |
| 491 | /** |
| 492 | * Associate a user data with this TURN session. The user data may then |
| 493 | * be retrieved later with pj_turn_session_get_user_data(). |
| 494 | * |
| 495 | * @param sess The TURN client session. |
| 496 | * @param user_data Arbitrary data. |
| 497 | * |
| 498 | * @return PJ_SUCCESS if the operation has been successful, |
| 499 | * or the appropriate error code on failure. |
| 500 | */ |
| 501 | PJ_DECL(pj_status_t) pj_turn_session_set_user_data(pj_turn_session *sess, |
| 502 | void *user_data); |
| 503 | |
| 504 | /** |
| 505 | * Retrieve the previously assigned user data associated with this TURN |
| 506 | * session. |
| 507 | * |
| 508 | * @param sess The TURN client session. |
| 509 | * |
| 510 | * @return The user/application data. |
| 511 | */ |
| 512 | PJ_DECL(void*) pj_turn_session_get_user_data(pj_turn_session *sess); |
| 513 | |
| 514 | |
| 515 | /** |
| 516 | * Configure message logging. By default all flags are enabled. |
| 517 | * |
| 518 | * @param sess The TURN client session. |
| 519 | * @param flags Bitmask combination of #pj_stun_sess_msg_log_flag |
| 520 | */ |
| 521 | PJ_DECL(void) pj_turn_session_set_log(pj_turn_session *sess, |
| 522 | unsigned flags); |
| 523 | |
| 524 | |
| 525 | /** |
| 526 | * Configure the SOFTWARE name to be sent in all STUN requests by the |
| 527 | * TURN session. |
| 528 | * |
| 529 | * @param sess The TURN client session. |
| 530 | * @param sw Software name string. If this argument is NULL or |
| 531 | * empty, the session will not include SOFTWARE attribute |
| 532 | * in STUN requests and responses. |
| 533 | * |
| 534 | * @return PJ_SUCCESS on success, or the appropriate error code. |
| 535 | */ |
| 536 | PJ_DECL(pj_status_t) pj_turn_session_set_software_name(pj_turn_session *sess, |
| 537 | const pj_str_t *sw); |
| 538 | |
| 539 | |
| 540 | /** |
| 541 | * Set the server or domain name of the server. Before the application |
| 542 | * can send Allocate request (with pj_turn_session_alloc()), it must first |
| 543 | * resolve the server address(es) using this function. This function will |
| 544 | * resolve the TURN server using DNS SRV resolution if the \a resolver |
| 545 | * is set. The server resolution process will complete asynchronously, |
| 546 | * and application will be notified in \a on_state() callback with the |
| 547 | * session state set to PJ_TURN_STATE_RESOLVED. |
| 548 | * |
| 549 | * Application may call with pj_turn_session_alloc() before the server |
| 550 | * resolution completes. In this case, the operation will be queued by |
| 551 | * the session, and it will be sent once the server resolution completes. |
| 552 | * |
| 553 | * @param sess The TURN client session. |
| 554 | * @param domain The domain, hostname, or IP address of the TURN |
| 555 | * server. When this parameter contains domain name, |
| 556 | * the \a resolver parameter must be set to activate |
| 557 | * DNS SRV resolution. |
| 558 | * @param default_port The default TURN port number to use when DNS SRV |
| 559 | * resolution is not used. If DNS SRV resolution is |
| 560 | * used, the server port number will be set from the |
| 561 | * DNS SRV records. |
| 562 | * @param resolver If this parameter is not NULL, then the \a domain |
| 563 | * parameter will be first resolved with DNS SRV and |
| 564 | * then fallback to using DNS A/AAAA resolution when |
| 565 | * DNS SRV resolution fails. If this parameter is |
| 566 | * NULL, the \a domain parameter will be resolved as |
| 567 | * hostname. |
| 568 | * |
| 569 | * @return PJ_SUCCESS if the operation has been successfully |
| 570 | * queued, or the appropriate error code on failure. |
| 571 | * When this function returns PJ_SUCCESS, the final |
| 572 | * result of the resolution process will be notified |
| 573 | * to application in \a on_state() callback. |
| 574 | */ |
| 575 | PJ_DECL(pj_status_t) pj_turn_session_set_server(pj_turn_session *sess, |
| 576 | const pj_str_t *domain, |
| 577 | int default_port, |
| 578 | pj_dns_resolver *resolver); |
| 579 | |
| 580 | |
| 581 | /** |
| 582 | * Set credential to be used to authenticate against TURN server. |
| 583 | * Application must call this function before sending Allocate request |
| 584 | * with pj_turn_session_alloc(). |
| 585 | * |
| 586 | * @param sess The TURN client session |
| 587 | * @param cred STUN credential to be used. |
| 588 | * |
| 589 | * @return PJ_SUCCESS if the operation has been successful, |
| 590 | * or the appropriate error code on failure. |
| 591 | */ |
| 592 | PJ_DECL(pj_status_t) pj_turn_session_set_credential(pj_turn_session *sess, |
| 593 | const pj_stun_auth_cred *cred); |
| 594 | |
| 595 | |
| 596 | /** |
| 597 | * Allocate a relay address/resource in the TURN server by sending TURN |
| 598 | * Allocate request. Application must first initiate the server resolution |
| 599 | * process with pj_turn_session_set_server() and set the credential to be |
| 600 | * used with pj_turn_session_set_credential() before calling this function. |
| 601 | * |
| 602 | * This function will complete asynchronously, and the application will be |
| 603 | * notified about the allocation result in \a on_state() callback. The |
| 604 | * TURN session state will move to PJ_TURN_STATE_READY if allocation is |
| 605 | * successful, and PJ_TURN_STATE_DEALLOCATING or greater state if allocation |
| 606 | * has failed. |
| 607 | * |
| 608 | * Once allocation has been successful, the TURN session will keep this |
| 609 | * allocation alive until the session is destroyed, by sending periodic |
| 610 | * allocation refresh to the TURN server. |
| 611 | * |
| 612 | * @param sess The TURN client session. |
| 613 | * @param param Optional TURN allocation parameter. |
| 614 | * |
| 615 | * @return PJ_SUCCESS if the operation has been successfully |
| 616 | * initiated or the appropriate error code on failure. |
| 617 | */ |
| 618 | PJ_DECL(pj_status_t) pj_turn_session_alloc(pj_turn_session *sess, |
| 619 | const pj_turn_alloc_param *param); |
| 620 | |
| 621 | |
| 622 | /** |
| 623 | * Create or renew permission in the TURN server for the specified peer IP |
| 624 | * addresses. Application must install permission for a particular (peer) |
| 625 | * IP address before it sends any data to that IP address, or otherwise |
| 626 | * the TURN server will drop the data. |
| 627 | * |
| 628 | * @param sess The TURN client session. |
| 629 | * @param addr_cnt Number of IP addresses. |
| 630 | * @param addr Array of peer IP addresses. Only the address family |
| 631 | * and IP address portion of the socket address matter. |
| 632 | * @param options Specify 1 to let the TURN client session automatically |
| 633 | * renew the permission later when they are about to |
| 634 | * expire. |
| 635 | * |
| 636 | * @return PJ_SUCCESS if the operation has been successfully |
| 637 | * issued, or the appropriate error code. Note that |
| 638 | * the operation itself will complete asynchronously. |
| 639 | */ |
| 640 | PJ_DECL(pj_status_t) pj_turn_session_set_perm(pj_turn_session *sess, |
| 641 | unsigned addr_cnt, |
| 642 | const pj_sockaddr addr[], |
| 643 | unsigned options); |
| 644 | |
| 645 | |
| 646 | /** |
| 647 | * Send a data to the specified peer address via the TURN relay. This |
| 648 | * function will encapsulate the data as STUN Send Indication or TURN |
| 649 | * ChannelData packet and send the message to the TURN server. The TURN |
| 650 | * server then will send the data to the peer. |
| 651 | * |
| 652 | * The allocation (pj_turn_session_alloc()) must have been successfully |
| 653 | * created before application can relay any data. |
| 654 | * |
| 655 | * Since TURN session is transport independent, this function will |
| 656 | * ultimately call \a on_send_pkt() callback to request the application |
| 657 | * to actually send the packet containing the data to the TURN server. |
| 658 | * |
| 659 | * @param sess The TURN client session. |
| 660 | * @param pkt The data/packet to be sent to peer. |
| 661 | * @param pkt_len Length of the data. |
| 662 | * @param peer_addr The remote peer address (the ultimate destination |
| 663 | * of the data, and not the TURN server address). |
| 664 | * @param addr_len Length of the address. |
| 665 | * |
| 666 | * @return PJ_SUCCESS if the operation has been successful, |
| 667 | * or the appropriate error code on failure. |
| 668 | */ |
| 669 | PJ_DECL(pj_status_t) pj_turn_session_sendto(pj_turn_session *sess, |
| 670 | const pj_uint8_t *pkt, |
| 671 | unsigned pkt_len, |
| 672 | const pj_sockaddr_t *peer_addr, |
| 673 | unsigned addr_len); |
| 674 | |
| 675 | /** |
| 676 | * Optionally establish channel binding for the specified a peer address. |
| 677 | * This function will assign a unique channel number for the peer address |
| 678 | * and request channel binding to the TURN server for this address. When |
| 679 | * a channel has been bound to a peer, the TURN client and TURN server |
| 680 | * will exchange data using ChannelData encapsulation format, which has |
| 681 | * lower bandwidth overhead than Send Indication (the default format used |
| 682 | * when peer address is not bound to a channel). |
| 683 | * |
| 684 | * This function will complete asynchronously, and application will be |
| 685 | * notified about the result in \a on_channel_bound() callback. |
| 686 | * |
| 687 | * @param sess The TURN client session. |
| 688 | * @param peer The remote peer address. |
| 689 | * @param addr_len Length of the address. |
| 690 | * |
| 691 | * @return PJ_SUCCESS if the operation has been successfully |
| 692 | * initiated, or the appropriate error code on failure. |
| 693 | */ |
| 694 | PJ_DECL(pj_status_t) pj_turn_session_bind_channel(pj_turn_session *sess, |
| 695 | const pj_sockaddr_t *peer, |
| 696 | unsigned addr_len); |
| 697 | |
| 698 | /** |
| 699 | * Notify TURN client session upon receiving a packet from server. Since |
| 700 | * the TURN session is transport independent, it does not read packet from |
| 701 | * any sockets, and rather relies on application giving it packets that |
| 702 | * are received from the TURN server. The session then processes this packet |
| 703 | * and decides whether it is part of TURN protocol exchange or if it is a |
| 704 | * data to be reported back to user, which in this case it will call the |
| 705 | * \a on_rx_data() callback. |
| 706 | * |
| 707 | * @param sess The TURN client session. |
| 708 | * @param pkt The packet as received from the TURN server. This |
| 709 | * should contain either STUN encapsulated message or |
| 710 | * a ChannelData packet. |
| 711 | * @param pkt_len The length of the packet. |
| 712 | * @param parsed_len Optional argument to receive the number of parsed |
| 713 | * or processed data from the packet. |
| 714 | * |
| 715 | * @return The function may return non-PJ_SUCCESS if it receives |
| 716 | * non-STUN and non-ChannelData packet, or if the |
| 717 | * \a on_rx_data() returns non-PJ_SUCCESS; |
| 718 | */ |
| 719 | PJ_DECL(pj_status_t) pj_turn_session_on_rx_pkt(pj_turn_session *sess, |
| 720 | void *pkt, |
| 721 | pj_size_t pkt_len, |
| 722 | pj_size_t *parsed_len); |
| 723 | |
| 724 | |
| 725 | /** |
| 726 | * @} |
| 727 | */ |
| 728 | |
| 729 | |
| 730 | PJ_END_DECL |
| 731 | |
| 732 | |
| 733 | #endif /* __PJNATH_TURN_SESSION_H__ */ |
| 734 | |