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 __PJSIP_SIP_TRANSPORT_H__ 21 #define __PJSIP_SIP_TRANSPORT_H__ 22 23 /** 24 * @file sip_transport.h 25 * @brief SIP Transport 26 */ 27 28 #include <pjsip/sip_msg.h> 29 #include <pjsip/sip_parser.h> 30 #include <pjsip/sip_resolve.h> 31 #include <pj/sock.h> 32 #include <pj/list.h> 33 #include <pj/ioqueue.h> 34 #include <pj/timer.h> 35 36 PJ_BEGIN_DECL 37 38 /** 39 * @defgroup PJSIP_TRANSPORT Transport 40 * @ingroup PJSIP_CORE 41 * @brief This is the transport framework. 42 * 43 * The transport framework is fully extensible. Please see 44 * <A HREF="/docs.htm">PJSIP Developer's Guide</A> PDF 45 * document for more information. 46 * 47 * Application MUST register at least one transport to PJSIP before any 48 * messages can be sent or received. Please see @ref PJSIP_TRANSPORT_UDP 49 * on how to create/register UDP transport to the transport framework. 50 * 51 * @{ 52 */ 53 54 /***************************************************************************** 55 * 56 * GENERAL TRANSPORT (NAMES, TYPES, ETC.) 57 * 58 *****************************************************************************/ 59 60 /* 61 * Forward declaration for transport factory (since it is referenced by 62 * the transport factory itself). 63 */ 64 typedef struct pjsip_tpfactory pjsip_tpfactory; 65 66 67 /** 68 * Flags for SIP transports. 69 */ 70 enum pjsip_transport_flags_e 71 { 72 PJSIP_TRANSPORT_RELIABLE = 1, /**< Transport is reliable. */ 73 PJSIP_TRANSPORT_SECURE = 2, /**< Transport is secure. */ 74 PJSIP_TRANSPORT_DATAGRAM = 4 /**< Datagram based transport. 75 (it's also assumed to be 76 connectionless) */ 77 }; 78 79 /** 80 * Check if transport tp is reliable. 81 */ 82 #define PJSIP_TRANSPORT_IS_RELIABLE(tp) \ 83 ((tp)->flag & PJSIP_TRANSPORT_RELIABLE) 84 85 /** 86 * Check if transport tp is secure. 87 */ 88 #define PJSIP_TRANSPORT_IS_SECURE(tp) \ 89 ((tp)->flag & PJSIP_TRANSPORT_SECURE) 90 91 /** 92 * Register new transport type to PJSIP. The PJSIP transport framework 93 * contains the info for some standard transports, as declared by 94 * #pjsip_transport_type_e. Application may use non-standard transport 95 * with PJSIP, but before it does so, it must register the information 96 * about the new transport type to PJSIP by calling this function. 97 * 98 * @param tp_flag The flags describing characteristics of this 99 * transport type. 100 * @param tp_name Transport type name. 101 * @param def_port Default port to be used for the transport. 102 * @param p_tp_type On successful registration, it will be filled with 103 * the registered type. This argument is optional. 104 * 105 * @return PJ_SUCCESS if registration is successful, or 106 * PJSIP_ETYPEEXISTS if the same transport type has 107 * already been registered. 108 */ 109 PJ_DECL(pj_status_t) pjsip_transport_register_type(unsigned tp_flag, 110 const char *tp_name, 111 int def_port, 112 int *p_tp_type); 113 114 115 /** 116 * Get the transport type from the transport name. 117 * 118 * @param name Transport name, such as "TCP", or "UDP". 119 * 120 * @return The transport type, or PJSIP_TRANSPORT_UNSPECIFIED if 121 * the name is not recognized as the name of supported 122 * transport. 123 */ 124 PJ_DECL(pjsip_transport_type_e) 125 pjsip_transport_get_type_from_name(const pj_str_t *name); 126 127 /** 128 * Get the transport type for the specified flags. 129 * 130 * @param flag The transport flag. 131 * 132 * @return Transport type. 133 */ 134 PJ_DECL(pjsip_transport_type_e) 135 pjsip_transport_get_type_from_flag(unsigned flag); 136 137 /** 138 * Get the socket address family of a given transport type. 139 * 140 * @param type Transport type. 141 * 142 * @return Transport type. 143 */ 144 PJ_DECL(int) pjsip_transport_type_get_af(pjsip_transport_type_e type); 145 146 /** 147 * Get transport flag from type. 148 * 149 * @param type Transport type. 150 * 151 * @return Transport flags. 152 */ 153 PJ_DECL(unsigned) 154 pjsip_transport_get_flag_from_type( pjsip_transport_type_e type ); 155 156 /** 157 * Get the default SIP port number for the specified type. 158 * 159 * @param type Transport type. 160 * 161 * @return The port number, which is the default SIP port number for 162 * the specified type. 163 */ 164 PJ_DECL(int) 165 pjsip_transport_get_default_port_for_type(pjsip_transport_type_e type); 166 167 /** 168 * Get transport type name. 169 * 170 * @param t Transport type. 171 * 172 * @return Transport name. 173 */ 174 PJ_DECL(const char*) pjsip_transport_get_type_name(pjsip_transport_type_e t); 175 176 /** 177 * Get longer description for the specified transport type. 178 * 179 * @param t Transport type. 180 * 181 * @return Transport description. 182 */ 183 PJ_DECL(const char*) pjsip_transport_get_type_desc(pjsip_transport_type_e t); 184 185 186 187 /***************************************************************************** 188 * 189 * TRANSPORT SELECTOR. 190 * 191 *****************************************************************************/ 192 193 /** 194 * This structure describes the type of data in pjsip_tpselector. 195 */ 196 typedef enum pjsip_tpselector_type 197 { 198 /** Transport is not specified. */ 199 PJSIP_TPSELECTOR_NONE, 200 201 /** Use the specific transport to send request. */ 202 PJSIP_TPSELECTOR_TRANSPORT, 203 204 /** Use the specific listener to send request. */ 205 PJSIP_TPSELECTOR_LISTENER, 206 207 } pjsip_tpselector_type; 208 209 210 /** 211 * This structure describes the transport/listener preference to be used 212 * when sending outgoing requests. 213 * 214 * Normally transport will be selected automatically according to rules about 215 * sending requests. But some applications (such as proxies or B2BUAs) may 216 * want to explicitly use specific transport to send requests, for example 217 * when they want to make sure that outgoing request should go from a specific 218 * network interface. 219 * 220 * The pjsip_tpselector structure is used for that purpose, i.e. to allow 221 * application specificly request that a particular transport/listener 222 * should be used to send request. This structure is used when calling 223 * pjsip_tsx_set_transport() and pjsip_dlg_set_transport(). 224 * 225 * If application disables connection reuse and wants to force creating 226 * a new transport, it needs to consider the following couple of things: 227 * - If it still wants to reuse an existing transport (if any), it 228 * needs to keep a reference to that transport and specifically set 229 * the transport to be used for sending requests. 230 * - Delete those existing transports manually when no longer needed. 231 */ 232 typedef struct pjsip_tpselector 233 { 234 /** The type of data in the union */ 235 pjsip_tpselector_type type; 236 237 /** 238 * Whether to disable reuse of an existing connection. 239 * This setting will be ignored if (type == PJSIP_TPSELECTOR_TRANSPORT) 240 * and transport in the union below is set. 241 */ 242 pj_bool_t disable_connection_reuse; 243 244 /** Union representing the transport/listener criteria to be used. */ 245 union { 246 pjsip_transport *transport; 247 pjsip_tpfactory *listener; 248 void *ptr; 249 } u; 250 251 } pjsip_tpselector; 252 253 254 /** 255 * Add transport/listener reference in the selector to prevent the specified 256 * transport/listener from being destroyed while application still has 257 * reference to it. 258 * 259 * @param sel The transport selector. 260 */ 261 PJ_DECL(void) pjsip_tpselector_add_ref(pjsip_tpselector *sel); 262 263 264 /** 265 * Decrement transport/listener reference in the selector. 266 * @param sel The transport selector 267 */ 268 PJ_DECL(void) pjsip_tpselector_dec_ref(pjsip_tpselector *sel); 269 270 271 /***************************************************************************** 272 * 273 * RECEIVE DATA BUFFER. 274 * 275 *****************************************************************************/ 276 277 /** 278 * A customized ioqueue async operation key which is used by transport 279 * to locate rdata when a pending read operation completes. 280 */ 281 typedef struct pjsip_rx_data_op_key 282 { 283 pj_ioqueue_op_key_t op_key; /**< ioqueue op_key. */ 284 pjsip_rx_data *rdata; /**< rdata associated with this */ 285 } pjsip_rx_data_op_key; 286 287 288 /** 289 * Incoming message buffer. 290 * This structure keep all the information regarding the received message. This 291 * buffer lifetime is only very short, normally after the transaction has been 292 * called, this buffer will be deleted/recycled. So care must be taken when 293 * allocating storage from the pool of this buffer. 294 */ 295 struct pjsip_rx_data 296 { 297 298 /** 299 * tp_info is part of rdata that remains static for the duration of the 300 * buffer. It is initialized when the buffer was created by transport. 301 */ 302 struct 303 { 304 /** Memory pool for this buffer. */ 305 pj_pool_t *pool; 306 307 /** The transport object which received this packet. */ 308 pjsip_transport *transport; 309 310 /** Other transport specific data to be attached to this buffer. */ 311 void *tp_data; 312 313 /** Ioqueue key. */ 314 pjsip_rx_data_op_key op_key; 315 316 } tp_info; 317 318 319 /** 320 * pkt_info is initialized by transport when it receives an incoming 321 * packet. 322 */ 323 struct 324 { 325 /** Time when the message was received. */ 326 pj_time_val timestamp; 327 328 /** Pointer to the original packet. */ 329 char packet[PJSIP_MAX_PKT_LEN]; 330 331 /** Zero termination for the packet. */ 332 pj_uint32_t zero; 333 334 /** The length of the packet received. */ 335 pj_ssize_t len; 336 337 /** The source address from which the packet was received. */ 338 pj_sockaddr src_addr; 339 340 /** The length of the source address. */ 341 int src_addr_len; 342 343 /** The IP source address string (NULL terminated). */ 344 char src_name[PJ_INET6_ADDRSTRLEN]; 345 346 /** The IP source port number. */ 347 int src_port; 348 349 } pkt_info; 350 351 352 /** 353 * msg_info is initialized by transport mgr (tpmgr) before this buffer 354 * is passed to endpoint. 355 */ 356 struct 357 { 358 /** Start of msg buffer. */ 359 char *msg_buf; 360 361 /** Length fo message. */ 362 int len; 363 364 /** The parsed message, if any. */ 365 pjsip_msg *msg; 366 367 /** Short description about the message. 368 * Application should use #pjsip_rx_data_get_info() instead. 369 */ 370 char *info; 371 372 /** The Call-ID header as found in the message. */ 373 pjsip_cid_hdr *cid; 374 375 /** The From header as found in the message. */ 376 pjsip_from_hdr *from; 377 378 /** The To header as found in the message. */ 379 pjsip_to_hdr *to; 380 381 /** The topmost Via header as found in the message. */ 382 pjsip_via_hdr *via; 383 384 /** The CSeq header as found in the message. */ 385 pjsip_cseq_hdr *cseq; 386 387 /** Max forwards header. */ 388 pjsip_max_fwd_hdr *max_fwd; 389 390 /** The first route header. */ 391 pjsip_route_hdr *route; 392 393 /** The first record-route header. */ 394 pjsip_rr_hdr *record_route; 395 396 /** Content-type header. */ 397 pjsip_ctype_hdr *ctype; 398 399 /** Content-length header. */ 400 pjsip_clen_hdr *clen; 401 402 /** "Require" header containing aggregates of all Require 403 * headers found in the message, or NULL. 404 */ 405 pjsip_require_hdr *require; 406 407 /** "Supported" header containing aggregates of all Supported 408 * headers found in the message, or NULL. 409 */ 410 pjsip_supported_hdr *supported; 411 412 /** The list of error generated by the parser when parsing 413 this message. 414 */ 415 pjsip_parser_err_report parse_err; 416 417 } msg_info; 418 419 420 /** 421 * endpt_info is initialized by endpoint after this buffer reaches 422 * endpoint. 423 */ 424 struct 425 { 426 /** 427 * Data attached by modules to this message. 428 */ 429 void *mod_data[PJSIP_MAX_MODULE]; 430 431 } endpt_info; 432 433 }; 434 435 /** 436 * Get printable information about the message in the rdata. 437 * 438 * @param rdata The receive data buffer. 439 * 440 * @return Printable information. 441 */ 442 PJ_DECL(char*) pjsip_rx_data_get_info(pjsip_rx_data *rdata); 443 444 /** 445 * Clone pjsip_rx_data. This will duplicate the contents of 446 * pjsip_rx_data and add reference count to the transport. 447 * Once application has finished using the cloned pjsip_rx_data, 448 * it must release it by calling #pjsip_rx_data_free_cloned(). 449 * 450 * By default (if flags is set to zero), this function copies the 451 * transport pointer in \a tp_info, duplicates the \a pkt_info, 452 * perform deep clone of the \a msg_info parts of the rdata, and 453 * fills the \a endpt_info (i.e. the \a mod_data) with zeros. 454 * 455 * @param src The source to be cloned. 456 * @param flags Optional flags. Must be zero for now. 457 * @param p_rdata Pointer to receive the cloned rdata. 458 * 459 * @return PJ_SUCCESS on success or the appropriate error. 460 */ 461 PJ_DECL(pj_status_t) pjsip_rx_data_clone(const pjsip_rx_data *src, 462 unsigned flags, 463 pjsip_rx_data **p_rdata); 464 465 /** 466 * Free cloned pjsip_rx_data. This function must be and must only 467 * be called for a cloned pjsip_rx_data. Specifically, it must NOT 468 * be called for the original pjsip_rx_data that is returned by 469 * transports. 470 * 471 * This function will free the memory used by the pjsip_rx_data and 472 * decrement the transport reference counter. 473 * 474 * @param rdata The receive data buffer. 475 * 476 * @return PJ_SUCCESS on success or the appropriate error. 477 */ 478 PJ_DECL(pj_status_t) pjsip_rx_data_free_cloned(pjsip_rx_data *rdata); 479 480 481 /***************************************************************************** 482 * 483 * TRANSMIT DATA BUFFER MANIPULATION. 484 * 485 *****************************************************************************/ 486 487 /** Customized ioqueue async operation key, used by transport to keep 488 * callback parameters. 489 */ 490 typedef struct pjsip_tx_data_op_key 491 { 492 /** ioqueue pending operation key. */ 493 pj_ioqueue_op_key_t key; 494 495 /** Transmit data associated with this key. */ 496 pjsip_tx_data *tdata; 497 498 /** Arbitrary token (attached by transport) */ 499 void *token; 500 501 /** Callback to be called when pending transmit operation has 502 completed. 503 */ 504 void (*callback)(pjsip_transport*,void*,pj_ssize_t); 505 } pjsip_tx_data_op_key; 506 507 508 /** 509 * Data structure for sending outgoing message. Application normally creates 510 * this buffer by calling #pjsip_endpt_create_tdata. 511 * 512 * The lifetime of this buffer is controlled by the reference counter in this 513 * structure, which is manipulated by calling #pjsip_tx_data_add_ref and 514 * #pjsip_tx_data_dec_ref. When the reference counter has reached zero, then 515 * this buffer will be destroyed. 516 * 517 * A transaction object normally will add reference counter to this buffer 518 * when application calls #pjsip_tsx_send_msg, because it needs to keep the 519 * message for retransmission. The transaction will release the reference 520 * counter once its state has reached final state. 521 */ 522 struct pjsip_tx_data 523 { 524 /** This is for transmission queue; it's managed by transports. */ 525 PJ_DECL_LIST_MEMBER(struct pjsip_tx_data); 526 527 /** Memory pool for this buffer. */ 528 pj_pool_t *pool; 529 530 /** A name to identify this buffer. */ 531 char obj_name[PJ_MAX_OBJ_NAME]; 532 533 /** Short information describing this buffer and the message in it. 534 * Application should use #pjsip_tx_data_get_info() instead of 535 * directly accessing this member. 536 */ 537 char *info; 538 539 /** For response message, this contains the reference to timestamp when 540 * the original request message was received. The value of this field 541 * is set when application creates response message to a request by 542 * calling #pjsip_endpt_create_response. 543 */ 544 pj_time_val rx_timestamp; 545 546 /** The transport manager for this buffer. */ 547 pjsip_tpmgr *mgr; 548 549 /** Ioqueue asynchronous operation key. */ 550 pjsip_tx_data_op_key op_key; 551 552 /** Lock object. */ 553 pj_lock_t *lock; 554 555 /** The message in this buffer. */ 556 pjsip_msg *msg; 557 558 /** Strict route header saved by #pjsip_process_route_set(), to be 559 * restored by #pjsip_restore_strict_route_set(). 560 */ 561 pjsip_route_hdr *saved_strict_route; 562 563 /** Buffer to the printed text representation of the message. When the 564 * content of this buffer is set, then the transport will send the content 565 * of this buffer instead of re-printing the message structure. If the 566 * message structure has changed, then application must invalidate this 567 * buffer by calling #pjsip_tx_data_invalidate_msg. 568 */ 569 pjsip_buffer buf; 570 571 /** Reference counter. */ 572 pj_atomic_t *ref_cnt; 573 574 /** Being processed by transport? */ 575 int is_pending; 576 577 /** Transport manager internal. */ 578 void *token; 579 580 /** Callback to be called when this tx_data has been transmitted. */ 581 void (*cb)(void*, pjsip_tx_data*, pj_ssize_t); 582 583 /** Destination information, to be used to determine the network address 584 * of the message. For a request, this information is initialized when 585 * the request is sent with #pjsip_endpt_send_request_stateless() and 586 * network address is resolved. For CANCEL request, this information 587 * will be copied from the original INVITE to make sure that the CANCEL 588 * request goes to the same physical network address as the INVITE 589 * request. 590 */ 591 struct 592 { 593 /** Server name. 594 */ 595 pj_str_t name; 596 597 /** Server addresses resolved. 598 */ 599 pjsip_server_addresses addr; 600 601 /** Current server address being tried. 602 */ 603 unsigned cur_addr; 604 605 } dest_info; 606 607 /** Transport information, only valid during on_tx_request() and 608 * on_tx_response() callback. 609 */ 610 struct 611 { 612 pjsip_transport *transport; /**< Transport being used. */ 613 pj_sockaddr dst_addr; /**< Destination address. */ 614 int dst_addr_len; /**< Length of address. */ 615 char dst_name[PJ_INET6_ADDRSTRLEN]; /**< Destination address. */ 616 int dst_port; /**< Destination port. */ 617 } tp_info; 618 619 /** 620 * Transport selector, to specify which transport to be used. 621 * The value here must be set with pjsip_tx_data_set_transport(), 622 * to allow reference counter to be set properly. 623 */ 624 pjsip_tpselector tp_sel; 625 626 /** 627 * Special flag to indicate that this transmit data is a request that has 628 * been updated with proper authentication response and is ready to be 629 * sent for retry. 630 */ 631 pj_bool_t auth_retry; 632 633 /** 634 * Arbitrary data attached by PJSIP modules. 635 */ 636 void *mod_data[PJSIP_MAX_MODULE]; 637 638 /** 639 * If via_addr is set, it will be used as the "sent-by" field of the 640 * Via header for outgoing requests as long as the request uses via_tp 641 * transport. Normally application should not use or access these fields. 642 */ 643 pjsip_host_port via_addr; /**< Via address. */ 644 const void *via_tp; /**< Via transport. */ 645 }; 646 647 648 /** 649 * Create a new, blank transmit buffer. The reference count is initialized 650 * to zero. 651 * 652 * @param mgr The transport manager. 653 * @param tdata Pointer to receive transmit data. 654 * 655 * @return PJ_SUCCESS, or the appropriate error code. 656 * 657 * @see pjsip_endpt_create_tdata 658 */ 659 PJ_DECL(pj_status_t) pjsip_tx_data_create( pjsip_tpmgr *mgr, 660 pjsip_tx_data **tdata ); 661 662 /** 663 * Add reference counter to the transmit buffer. The reference counter controls 664 * the life time of the buffer, ie. when the counter reaches zero, then it 665 * will be destroyed. 666 * 667 * @param tdata The transmit buffer. 668 */ 669 PJ_DECL(void) pjsip_tx_data_add_ref( pjsip_tx_data *tdata ); 670 671 /** 672 * Decrement reference counter of the transmit buffer. 673 * When the transmit buffer is no longer used, it will be destroyed and 674 * caller is informed with PJSIP_EBUFDESTROYED return status. 675 * 676 * @param tdata The transmit buffer data. 677 * @return This function will always succeeded eventhough the return 678 * status is non-zero. A status PJSIP_EBUFDESTROYED will be 679 * returned to inform that buffer is destroyed. 680 */ 681 PJ_DECL(pj_status_t) pjsip_tx_data_dec_ref( pjsip_tx_data *tdata ); 682 683 /** 684 * Print the SIP message to transmit data buffer's internal buffer. This 685 * may allocate memory for the buffer, if the buffer has not been allocated 686 * yet, and encode the SIP message to that buffer. 687 * 688 * @param tdata The transmit buffer. 689 * 690 * @return PJ_SUCCESS on success of the appropriate error code. 691 */ 692 PJ_DECL(pj_status_t) pjsip_tx_data_encode(pjsip_tx_data *tdata); 693 694 /** 695 * Check if transmit data buffer contains a valid message. 696 * 697 * @param tdata The transmit buffer. 698 * @return Non-zero (PJ_TRUE) if buffer contains a valid message. 699 */ 700 PJ_DECL(pj_bool_t) pjsip_tx_data_is_valid( pjsip_tx_data *tdata ); 701 702 /** 703 * Invalidate the print buffer to force message to be re-printed. Call 704 * when the message has changed after it has been printed to buffer. The 705 * message is printed to buffer normally by transport when it is about to be 706 * sent to the wire. Subsequent sending of the message will not cause 707 * the message to be re-printed, unless application invalidates the buffer 708 * by calling this function. 709 * 710 * @param tdata The transmit buffer. 711 */ 712 PJ_DECL(void) pjsip_tx_data_invalidate_msg( pjsip_tx_data *tdata ); 713 714 /** 715 * Get short printable info about the transmit data. This will normally return 716 * short information about the message. 717 * 718 * @param tdata The transmit buffer. 719 * 720 * @return Null terminated info string. 721 */ 722 PJ_DECL(char*) pjsip_tx_data_get_info( pjsip_tx_data *tdata ); 723 724 /** 725 * Set the explicit transport to be used when sending this transmit data. 726 * Application should not need to call this function, but rather use 727 * pjsip_tsx_set_transport() and pjsip_dlg_set_transport() instead (which 728 * will call this function). 729 * 730 * @param tdata The transmit buffer. 731 * @param sel Transport selector. 732 * 733 * @return PJ_SUCCESS on success. 734 */ 735 PJ_DECL(pj_status_t) pjsip_tx_data_set_transport(pjsip_tx_data *tdata, 736 const pjsip_tpselector *sel); 737 738 /** 739 * Clone pjsip_tx_data. This will duplicate the message contents of 740 * pjsip_tx_data (pjsip_tx_data.msg) and add reference count to the tdata. 741 * Once application has finished using the cloned pjsip_tx_data, 742 * it must release it by calling #pjsip_tx_data_dec_ref(). 743 * Currently, this will only clone response message. 744 * 745 * @param src The source to be cloned. 746 * @param flags Optional flags. Must be zero for now. 747 * @param p_rdata Pointer to receive the cloned tdata. 748 * 749 * @return PJ_SUCCESS on success or the appropriate error. 750 */ 751 PJ_DECL(pj_status_t) pjsip_tx_data_clone(const pjsip_tx_data *src, 752 unsigned flags, 753 pjsip_tx_data **p_rdata); 754 755 /***************************************************************************** 756 * 757 * TRANSPORT 758 * 759 *****************************************************************************/ 760 /** 761 * Type of callback to receive transport operation status. 762 */ 763 typedef void (*pjsip_transport_callback)(pjsip_transport *tp, void *token, 764 pj_ssize_t sent_bytes); 765 766 /** 767 * This structure describes transport key to be registered to hash table. 768 */ 769 typedef struct pjsip_transport_key 770 { 771 /** 772 * Transport type. 773 */ 774 long type; 775 776 /** 777 * Destination address. 778 */ 779 pj_sockaddr rem_addr; 780 781 } pjsip_transport_key; 782 783 784 /** 785 * Enumeration of transport direction types. 786 */ 787 typedef enum pjsip_transport_dir 788 { 789 PJSIP_TP_DIR_NONE, /**< Direction not set, normally used by 790 connectionless transports such as 791 UDP transport. */ 792 PJSIP_TP_DIR_OUTGOING, /**< Outgoing connection or client mode, 793 this is only for connection-oriented 794 transports. */ 795 PJSIP_TP_DIR_INCOMING, /**< Incoming connection or server mode, 796 this is only for connection-oriented 797 transports. */ 798 } pjsip_transport_dir; 799 800 801 /** 802 * This structure represent the "public" interface of a SIP transport. 803 * Applications normally extend this structure to include transport 804 * specific members. 805 */ 806 struct pjsip_transport 807 { 808 char obj_name[PJ_MAX_OBJ_NAME]; /**< Name. */ 809 810 pj_pool_t *pool; /**< Pool used by transport. */ 811 pj_atomic_t *ref_cnt; /**< Reference counter. */ 812 pj_lock_t *lock; /**< Lock object. */ 813 pj_grp_lock_t *grp_lock; /**< Group lock for sync with 814 ioqueue and timer. */ 815 pj_bool_t tracing; /**< Tracing enabled? */ 816 pj_bool_t is_shutdown; /**< Being shutdown? */ 817 pj_bool_t is_destroying; /**< Destroy in progress? */ 818 819 /** Key for indexing this transport in hash table. */ 820 pjsip_transport_key key; 821 822 char *type_name; /**< Type name. */ 823 unsigned flag; /**< #pjsip_transport_flags_e */ 824 char *info; /**< Transport info/description.*/ 825 826 int addr_len; /**< Length of addresses. */ 827 pj_sockaddr local_addr; /**< Bound address. */ 828 pjsip_host_port local_name; /**< Published name (eg. STUN). */ 829 pjsip_host_port remote_name; /**< Remote address name. */ 830 pjsip_transport_dir dir; /**< Connection direction. */ 831 832 pjsip_endpoint *endpt; /**< Endpoint instance. */ 833 pjsip_tpmgr *tpmgr; /**< Transport manager. */ 834 pjsip_tpfactory *factory; /**< Factory instance. Note: it 835 may be invalid/shutdown. */ 836 pj_timer_entry idle_timer; /**< Timer when ref cnt is zero.*/ 837 838 pj_timestamp last_recv_ts; /**< Last time receiving data. */ 839 pj_size_t last_recv_len; /**< Last received data length. */ 840 841 void *data; /**< Internal transport data. */ 842 843 /** 844 * Function to be called by transport manager to send SIP message. 845 * 846 * @param transport The transport to send the message. 847 * @param packet The buffer to send. 848 * @param length The length of the buffer to send. 849 * @param op_key Completion token, which will be supplied to 850 * caller when pending send operation completes. 851 * @param rem_addr The remote destination address. 852 * @param addr_len Size of remote address. 853 * @param callback If supplied, the callback will be called 854 * once a pending transmission has completed. If 855 * the function completes immediately (i.e. return 856 * code is not PJ_EPENDING), the callback will not 857 * be called. 858 * 859 * @return Should return PJ_SUCCESS only if data has been 860 * succesfully queued to operating system for 861 * transmission. Otherwise it may return PJ_EPENDING 862 * if the underlying transport can not send the 863 * data immediately and will send it later, which in 864 * this case caller doesn't have to do anything 865 * except wait the calback to be called, if it 866 * supplies one. 867 * Other return values indicate the error code. 868 */ 869 pj_status_t (*send_msg)(pjsip_transport *transport, 870 pjsip_tx_data *tdata, 871 const pj_sockaddr_t *rem_addr, 872 int addr_len, 873 void *token, 874 pjsip_transport_callback callback); 875 876 /** 877 * Instruct the transport to initiate graceful shutdown procedure. 878 * After all objects release their reference to this transport, 879 * the transport will be deleted. 880 * 881 * Note that application MUST use #pjsip_transport_shutdown() instead. 882 * 883 * @param transport The transport. 884 * 885 * @return PJ_SUCCESS on success. 886 */ 887 pj_status_t (*do_shutdown)(pjsip_transport *transport); 888 889 /** 890 * Forcefully destroy this transport regardless whether there are 891 * objects that currently use this transport. This function should only 892 * be called by transport manager or other internal objects (such as the 893 * transport itself) who know what they're doing. Application should use 894 * #pjsip_transport_shutdown() instead. 895 * 896 * @param transport The transport. 897 * 898 * @return PJ_SUCCESS on success. 899 */ 900 pj_status_t (*destroy)(pjsip_transport *transport); 901 902 /* 903 * Application may extend this structure.. 904 */ 905 }; 906 907 908 /** 909 * Register a transport instance to the transport manager. This function 910 * is normally called by the transport instance when it is created 911 * by application. 912 * 913 * @param mgr The transport manager. 914 * @param tp The new transport to be registered. 915 * 916 * @return PJ_SUCCESS on success. 917 */ 918 PJ_DECL(pj_status_t) pjsip_transport_register( pjsip_tpmgr *mgr, 919 pjsip_transport *tp ); 920 921 922 /** 923 * Start graceful shutdown procedure for this transport. After graceful 924 * shutdown has been initiated, no new reference can be obtained for 925 * the transport. However, existing objects that currently uses the 926 * transport may still use this transport to send and receive packets. 927 * 928 * After all objects release their reference to this transport, 929 * the transport will be destroyed immediately. 930 * 931 * @param tp The transport. 932 * 933 * @return PJ_SUCCESS on success. 934 */ 935 PJ_DECL(pj_status_t) pjsip_transport_shutdown(pjsip_transport *tp); 936 937 /** 938 * Start shutdown procedure for this transport. If \a force is false, 939 * the API is the same as #pjsip_transport_shutdown(), while 940 * if \a force is true, existing transport users will immediately 941 * receive PJSIP_TP_STATE_DISCONNECTED notification and should not 942 * use the transport anymore. In either case, transport will 943 * only be destroyed after all objects release their references. 944 * 945 * @param tp The transport. 946 * @param force Force transport to immediately send 947 * disconnection state notification. 948 * 949 * @return PJ_SUCCESS on success. 950 */ 951 PJ_DECL(pj_status_t) pjsip_transport_shutdown2(pjsip_transport *tp, 952 pj_bool_t force); 953 954 /** 955 * Destroy a transport when there is no object currently uses the transport. 956 * This function is normally called internally by transport manager or the 957 * transport itself. Application should use #pjsip_transport_shutdown() 958 * instead. 959 * 960 * @param tp The transport instance. 961 * 962 * @return PJ_SUCCESS on success or the appropriate error code. 963 * Some of possible errors are PJSIP_EBUSY if the 964 * transport's reference counter is not zero. 965 */ 966 PJ_DECL(pj_status_t) pjsip_transport_destroy( pjsip_transport *tp); 967 968 /** 969 * Add reference counter to the specified transport. Any objects that wishes 970 * to keep the reference of the transport MUST increment the transport's 971 * reference counter to prevent it from being destroyed. 972 * 973 * @param tp The transport instance. 974 * 975 * @return PJ_SUCCESS on success or the appropriate error code. 976 */ 977 PJ_DECL(pj_status_t) pjsip_transport_add_ref( pjsip_transport *tp ); 978 979 /** 980 * Decrement reference counter of the specified transport. When an object no 981 * longer want to keep the reference to the transport, it must decrement the 982 * reference counter. When the reference counter of the transport reaches 983 * zero, the transport manager will start the idle timer to destroy the 984 * transport if no objects acquire the reference counter during the idle 985 * interval. 986 * 987 * @param tp The transport instance. 988 * 989 * @return PJ_SUCCESS on success. 990 */ 991 PJ_DECL(pj_status_t) pjsip_transport_dec_ref( pjsip_transport *tp ); 992 993 994 /** 995 * This function is called by transport instances to report an incoming 996 * packet to the transport manager. The transport manager then would try to 997 * parse all SIP messages in the packet, and for each parsed SIP message, it 998 * would report the message to the SIP endpoint (#pjsip_endpoint). 999 * 1000 * @param mgr The transport manager instance. 1001 * @param rdata The receive data buffer containing the packet. The 1002 * transport MUST fully initialize tp_info and pkt_info 1003 * member of the rdata. 1004 * 1005 * @return The number of bytes successfully processed from the 1006 * packet. If the transport is datagram oriented, the 1007 * value will be equal to the size of the packet. For 1008 * stream oriented transport (e.g. TCP, TLS), the value 1009 * returned may be less than the packet size, if 1010 * partial message is received. The transport then MUST 1011 * keep the remainder part and report it again to 1012 * this function once more data/packet is received. 1013 */ 1014 PJ_DECL(pj_ssize_t) pjsip_tpmgr_receive_packet(pjsip_tpmgr *mgr, 1015 pjsip_rx_data *rdata); 1016 1017 1018 /***************************************************************************** 1019 * 1020 * TRANSPORT FACTORY 1021 * 1022 *****************************************************************************/ 1023 1024 1025 /** 1026 * A transport factory is normally used for connection oriented transports 1027 * (such as TCP or TLS) to create instances of transports. It registers 1028 * a new transport type to the transport manager, and the transport manager 1029 * would ask the factory to create a transport instance when it received 1030 * command from application to send a SIP message using the specified 1031 * transport type. 1032 */ 1033 struct pjsip_tpfactory 1034 { 1035 /** This list is managed by transport manager. */ 1036 PJ_DECL_LIST_MEMBER(struct pjsip_tpfactory); 1037 1038 char obj_name[PJ_MAX_OBJ_NAME]; /**< Name. */ 1039 1040 pj_pool_t *pool; /**< Owned memory pool. */ 1041 pj_lock_t *lock; /**< Lock object. */ 1042 1043 pjsip_transport_type_e type; /**< Transport type. */ 1044 char *type_name; /**< Type string name. */ 1045 unsigned flag; /**< Transport flag. */ 1046 char *info; /**< Transport info/description.*/ 1047 1048 pj_sockaddr local_addr; /**< Bound address. */ 1049 pjsip_host_port addr_name; /**< Published name. */ 1050 1051 /** 1052 * Create new outbound connection suitable for sending SIP message 1053 * to specified remote address. 1054 * Note that the factory is responsible for both creating the 1055 * transport and registering it to the transport manager. 1056 */ 1057 pj_status_t (*create_transport)(pjsip_tpfactory *factory, 1058 pjsip_tpmgr *mgr, 1059 pjsip_endpoint *endpt, 1060 const pj_sockaddr *rem_addr, 1061 int addr_len, 1062 pjsip_transport **transport); 1063 1064 /** 1065 * Create new outbound connection suitable for sending SIP message 1066 * to specified remote address by also considering outgoing SIP 1067 * message data. 1068 * Note that the factory is responsible for both creating the 1069 * transport and registering it to the transport manager. 1070 */ 1071 pj_status_t (*create_transport2)(pjsip_tpfactory *factory, 1072 pjsip_tpmgr *mgr, 1073 pjsip_endpoint *endpt, 1074 const pj_sockaddr *rem_addr, 1075 int addr_len, 1076 pjsip_tx_data *tdata, 1077 pjsip_transport **transport); 1078 1079 /** 1080 * Destroy the listener. 1081 */ 1082 pj_status_t (*destroy)(pjsip_tpfactory *factory); 1083 1084 /* 1085 * Application may extend this structure.. 1086 */ 1087 }; 1088 1089 1090 1091 /** 1092 * Register a transport factory. 1093 * 1094 * @param mgr The transport manager. 1095 * @param tpf Transport factory. 1096 * 1097 * @return PJ_SUCCESS if listener was successfully created. 1098 */ 1099 PJ_DECL(pj_status_t) pjsip_tpmgr_register_tpfactory(pjsip_tpmgr *mgr, 1100 pjsip_tpfactory *tpf); 1101 1102 /** 1103 * Unregister factory. 1104 * 1105 * @param mgr The transport manager. 1106 * @param tpf Transport factory. 1107 * 1108 * @return PJ_SUCCESS is sucessfully unregistered. 1109 */ 1110 PJ_DECL(pj_status_t) pjsip_tpmgr_unregister_tpfactory(pjsip_tpmgr *mgr, 1111 pjsip_tpfactory *tpf); 1112 1113 1114 /***************************************************************************** 1115 * 1116 * TRANSPORT MANAGER 1117 * 1118 *****************************************************************************/ 1119 1120 /** 1121 * Type of callback to be called when transport manager receives incoming 1122 * SIP message. 1123 * 1124 * @param ep Endpoint. 1125 * @param status Receiption status. 1126 * @param rd Received packet. 1127 */ 1128 typedef void (*pjsip_rx_callback)(pjsip_endpoint *ep, pj_status_t status, 1129 pjsip_rx_data *rd); 1130 1131 /** 1132 * Type of callback to be called before transport manager is about 1133 * to transmit SIP message. 1134 * 1135 * @param ep Endpoint. 1136 * @param td Transmit data. 1137 */ 1138 typedef pj_status_t (*pjsip_tx_callback)(pjsip_endpoint *ep, pjsip_tx_data*td); 1139 1140 /** 1141 * Create a transport manager. Normally application doesn't need to call 1142 * this function directly, since a transport manager will be created and 1143 * destroyed automatically by the SIP endpoint. 1144 * 1145 * @param pool Pool. 1146 * @param endpt Endpoint instance. 1147 * @param rx_cb Callback to receive incoming message. 1148 * @param tx_cb Callback to be called before transport manager is sending 1149 * outgoing message. 1150 * @param p_mgr Pointer to receive the new transport manager. 1151 * 1152 * @return PJ_SUCCESS or the appropriate error code on error. 1153 */ 1154 PJ_DECL(pj_status_t) pjsip_tpmgr_create( pj_pool_t *pool, 1155 pjsip_endpoint * endpt, 1156 pjsip_rx_callback rx_cb, 1157 pjsip_tx_callback tx_cb, 1158 pjsip_tpmgr **p_mgr); 1159 1160 1161 /** 1162 * Find out the appropriate local address info (IP address and port) to 1163 * advertise in Contact header based on the remote address to be 1164 * contacted. The local address info would be the address name of the 1165 * transport or listener which will be used to send the request. 1166 * 1167 * In this implementation, it will only select the transport based on 1168 * the transport type in the request. 1169 * 1170 * @see pjsip_tpmgr_find_local_addr2() 1171 * 1172 * @param tpmgr The transport manager. 1173 * @param pool Pool to allocate memory for the IP address. 1174 * @param type Destination address to contact. 1175 * @param sel Optional pointer to prefered transport, if any. 1176 * @param ip_addr Pointer to receive the IP address. 1177 * @param port Pointer to receive the port number. 1178 * 1179 * @return PJ_SUCCESS, or the appropriate error code. 1180 */ 1181 PJ_DECL(pj_status_t) pjsip_tpmgr_find_local_addr( pjsip_tpmgr *tpmgr, 1182 pj_pool_t *pool, 1183 pjsip_transport_type_e type, 1184 const pjsip_tpselector *sel, 1185 pj_str_t *ip_addr, 1186 int *port); 1187 1188 /** 1189 * Parameter for pjsip_tpmgr_find_local_addr2() function. 1190 */ 1191 typedef struct pjsip_tpmgr_fla2_param 1192 { 1193 /** 1194 * Specify transport type to use. This must be set. 1195 */ 1196 pjsip_transport_type_e tp_type; 1197 1198 /** 1199 * Optional pointer to preferred transport, if any. 1200 */ 1201 const pjsip_tpselector *tp_sel; 1202 1203 /** 1204 * Destination host, if known. The destination host is needed 1205 * if \a local_if field below is set. 1206 */ 1207 pj_str_t dst_host; 1208 1209 /** 1210 * Specify if the function should return which local interface 1211 * to use for the specified destination in \a dst_host. By definition, 1212 * the returned address will always be local interface address. 1213 */ 1214 pj_bool_t local_if; 1215 1216 /** 1217 * The returned address. 1218 */ 1219 pj_str_t ret_addr; 1220 1221 /** 1222 * The returned port. 1223 */ 1224 pj_uint16_t ret_port; 1225 1226 /** 1227 * Returned pointer to the transport. Only set if local_if is set. 1228 */ 1229 const void *ret_tp; 1230 1231 } pjsip_tpmgr_fla2_param; 1232 1233 /** 1234 * Initialize with default values. 1235 * 1236 * @param prm The parameter to be initialized. 1237 */ 1238 PJ_DECL(void) pjsip_tpmgr_fla2_param_default(pjsip_tpmgr_fla2_param *prm); 1239 1240 /** 1241 * Find out the appropriate local address info (IP address and port) to 1242 * advertise in Contact or Via header header based on the remote address 1243 * to be contacted. The local address info would be the address name of the 1244 * transport or listener which will be used to send the request. 1245 * 1246 * @see pjsip_tpmgr_find_local_addr() 1247 * 1248 * @param tpmgr The transport manager. 1249 * @param pool Pool to allocate memory for the IP address. 1250 * @param param Function input and output parameters. 1251 * 1252 * @return PJ_SUCCESS, or the appropriate error code. 1253 */ 1254 PJ_DECL(pj_status_t) pjsip_tpmgr_find_local_addr2(pjsip_tpmgr *tpmgr, 1255 pj_pool_t *pool, 1256 pjsip_tpmgr_fla2_param *prm); 1257 1258 /** 1259 * Return number of transports currently registered to the transport 1260 * manager. 1261 * 1262 * @param mgr The transport manager. 1263 * 1264 * @return Number of transports. 1265 */ 1266 PJ_DECL(unsigned) pjsip_tpmgr_get_transport_count(pjsip_tpmgr *mgr); 1267 1268 1269 /** 1270 * Destroy a transport manager. Normally application doesn't need to call 1271 * this function directly, since a transport manager will be created and 1272 * destroyed automatically by the SIP endpoint. 1273 * 1274 * @param mgr The transport manager. 1275 * 1276 * @return PJ_SUCCESS on success. 1277 */ 1278 PJ_DECL(pj_status_t) pjsip_tpmgr_destroy(pjsip_tpmgr *mgr); 1279 1280 1281 /** 1282 * Dump transport info and status to log. 1283 * 1284 * @param mgr The transport manager. 1285 */ 1286 PJ_DECL(void) pjsip_tpmgr_dump_transports(pjsip_tpmgr *mgr); 1287 1288 1289 /***************************************************************************** 1290 * 1291 * PUBLIC API 1292 * 1293 *****************************************************************************/ 1294 1295 1296 /** 1297 * Find transport to be used to send message to remote destination. If no 1298 * suitable transport is found, a new one will be created. 1299 * 1300 * This is an internal function since normally application doesn't have access 1301 * to transport manager. Application should use pjsip_endpt_acquire_transport() 1302 * instead. 1303 * 1304 * @param mgr The transport manager instance. 1305 * @param type The type of transport to be acquired. 1306 * @param remote The remote address to send message to. 1307 * @param addr_len Length of the remote address. 1308 * @param sel Optional pointer to transport selector instance which is 1309 * used to find explicit transport, if required. 1310 * @param tp Pointer to receive the transport instance, if one is found. 1311 * 1312 * @return PJ_SUCCESS on success, or the appropriate error code. 1313 */ 1314 PJ_DECL(pj_status_t) pjsip_tpmgr_acquire_transport(pjsip_tpmgr *mgr, 1315 pjsip_transport_type_e type, 1316 const pj_sockaddr_t *remote, 1317 int addr_len, 1318 const pjsip_tpselector *sel, 1319 pjsip_transport **tp); 1320 1321 /** 1322 * Find suitable transport for sending SIP message to specified remote 1323 * destination by also considering the outgoing SIP message. If no suitable 1324 * transport is found, a new one will be created. 1325 * 1326 * This is an internal function since normally application doesn't have access 1327 * to transport manager. Application should use pjsip_endpt_acquire_transport2() 1328 * instead. 1329 * 1330 * @param mgr The transport manager instance. 1331 * @param type The type of transport to be acquired. 1332 * @param remote The remote address to send message to. 1333 * @param addr_len Length of the remote address. 1334 * @param sel Optional pointer to transport selector instance which is 1335 * used to find explicit transport, if required. 1336 * @param tdata Optional pointer to data to be sent. 1337 * @param tp Pointer to receive the transport instance, if one is found. 1338 * 1339 * @return PJ_SUCCESS on success, or the appropriate error code. 1340 */ 1341 PJ_DECL(pj_status_t) pjsip_tpmgr_acquire_transport2(pjsip_tpmgr *mgr, 1342 pjsip_transport_type_e type, 1343 const pj_sockaddr_t *remote, 1344 int addr_len, 1345 const pjsip_tpselector *sel, 1346 pjsip_tx_data *tdata, 1347 pjsip_transport **tp); 1348 1349 /** 1350 * Type of callback to receive notification when message or raw data 1351 * has been sent. 1352 * 1353 * @param token The token that was given when calling the function 1354 * to send message or raw data. 1355 * @param tdata The transmit buffer used to send the message. 1356 * @param bytes_sent Number of bytes sent. On success, the value will be 1357 * positive number indicating the number of bytes sent. 1358 * On failure, the value will be a negative number of 1359 * the error code (i.e. bytes_sent = -status). 1360 */ 1361 typedef void (*pjsip_tp_send_callback)(void *token, pjsip_tx_data *tdata, 1362 pj_ssize_t bytes_sent); 1363 1364 1365 /** 1366 * This is a low-level function to send a SIP message using the specified 1367 * transport to the specified destination. 1368 * 1369 * @param tr The SIP transport to be used. 1370 * @param tdata Transmit data buffer containing SIP message. 1371 * @param addr Destination address. 1372 * @param addr_len Length of destination address. 1373 * @param token Arbitrary token to be returned back to callback. 1374 * @param cb Optional callback to be called to notify caller about 1375 * the completion status of the pending send operation. 1376 * 1377 * @return If the message has been sent successfully, this function 1378 * will return PJ_SUCCESS and the callback will not be 1379 * called. If message cannot be sent immediately, this 1380 * function will return PJ_EPENDING, and application will 1381 * be notified later about the completion via the callback. 1382 * Any statuses other than PJ_SUCCESS or PJ_EPENDING 1383 * indicates immediate failure, and in this case the 1384 * callback will not be called. 1385 */ 1386 PJ_DECL(pj_status_t) pjsip_transport_send( pjsip_transport *tr, 1387 pjsip_tx_data *tdata, 1388 const pj_sockaddr_t *addr, 1389 int addr_len, 1390 void *token, 1391 pjsip_tp_send_callback cb); 1392 1393 1394 /** 1395 * This is a low-level function to send raw data to a destination. 1396 * 1397 * See also #pjsip_endpt_send_raw() and #pjsip_endpt_send_raw_to_uri(). 1398 * 1399 * @param mgr Transport manager. 1400 * @param tp_type Transport type. 1401 * @param sel Optional pointer to transport selector instance if 1402 * application wants to use a specific transport instance 1403 * rather then letting transport manager finds the suitable 1404 * transport. 1405 * @param tdata Optional transmit data buffer to be used. If this value 1406 * is NULL, this function will create one internally. If 1407 * tdata is specified, this function will decrement the 1408 * reference counter upon completion. 1409 * @param raw_data The data to be sent. 1410 * @param data_len The length of the data. 1411 * @param addr Destination address. 1412 * @param addr_len Length of destination address. 1413 * @param token Arbitrary token to be returned back to callback. 1414 * @param cb Optional callback to be called to notify caller about 1415 * the completion status of the pending send operation. 1416 * 1417 * @return If the message has been sent successfully, this function 1418 * will return PJ_SUCCESS and the callback will not be 1419 * called. If message cannot be sent immediately, this 1420 * function will return PJ_EPENDING, and application will 1421 * be notified later about the completion via the callback. 1422 * Any statuses other than PJ_SUCCESS or PJ_EPENDING 1423 * indicates immediate failure, and in this case the 1424 * callback will not be called. 1425 */ 1426 PJ_DECL(pj_status_t) pjsip_tpmgr_send_raw(pjsip_tpmgr *mgr, 1427 pjsip_transport_type_e tp_type, 1428 const pjsip_tpselector *sel, 1429 pjsip_tx_data *tdata, 1430 const void *raw_data, 1431 pj_size_t data_len, 1432 const pj_sockaddr_t *addr, 1433 int addr_len, 1434 void *token, 1435 pjsip_tp_send_callback cb); 1436 1437 1438 /** 1439 * Enumeration of transport state types. 1440 */ 1441 typedef enum pjsip_transport_state 1442 { 1443 PJSIP_TP_STATE_CONNECTED, /**< Transport connected, applicable only 1444 to connection-oriented transports 1445 such as TCP and TLS. */ 1446 PJSIP_TP_STATE_DISCONNECTED, /**< Transport disconnected, applicable 1447 only to connection-oriented 1448 transports such as TCP and TLS. */ 1449 PJSIP_TP_STATE_SHUTDOWN, /**< Transport shutdown, either 1450 due to TCP/TLS disconnect error 1451 from the network, or when shutdown 1452 is initiated by PJSIP itself. */ 1453 PJSIP_TP_STATE_DESTROY, /**< Transport destroy, when transport 1454 is about to be destroyed. */ 1455 } pjsip_transport_state; 1456 1457 1458 /** 1459 * Definition of transport state listener key. 1460 */ 1461 typedef void pjsip_tp_state_listener_key; 1462 1463 /** 1464 * Structure of transport state info passed by #pjsip_tp_state_callback. 1465 */ 1466 typedef struct pjsip_transport_state_info { 1467 /** 1468 * The last error code related to the transport state. 1469 */ 1470 pj_status_t status; 1471 1472 /** 1473 * Optional extended info, the content is specific for each transport type. 1474 */ 1475 void *ext_info; 1476 1477 /** 1478 * Optional user data. In global transport state notification, this will 1479 * always be NULL. 1480 */ 1481 void *user_data; 1482 1483 } pjsip_transport_state_info; 1484 1485 1486 /** 1487 * Type of callback to receive transport state notifications, such as 1488 * transport connected/disconnected. Application may shutdown the transport 1489 * in this callback. 1490 * 1491 * @param tp The transport instance. 1492 * @param state The transport state. 1493 * @param info The transport state info. 1494 */ 1495 typedef void (*pjsip_tp_state_callback)( 1496 pjsip_transport *tp, 1497 pjsip_transport_state state, 1498 const pjsip_transport_state_info *info); 1499 1500 1501 /** 1502 * Set callback of global transport state notification. The caller will be 1503 * notified whenever the state of any transport is changed. The type of events 1504 * are defined in #pjsip_transport_state. 1505 * 1506 * Note that this function will override the existing callback, if any, so 1507 * application is recommended to keep the old callback and manually forward 1508 * the notification to the old callback, otherwise other component that 1509 * concerns about the transport state will no longer receive transport state 1510 * events. 1511 * 1512 * @param mgr Transport manager. 1513 * @param cb Callback to be called to notify caller about transport 1514 * state changing. 1515 * 1516 * @return PJ_SUCCESS on success, or the appropriate error code. 1517 */ 1518 PJ_DECL(pj_status_t) pjsip_tpmgr_set_state_cb(pjsip_tpmgr *mgr, 1519 pjsip_tp_state_callback cb); 1520 1521 1522 /** 1523 * Get the callback of global transport state notification. 1524 * 1525 * @param mgr Transport manager. 1526 * 1527 * @return The transport state callback or NULL if it is not set. 1528 */ 1529 PJ_DECL(pjsip_tp_state_callback) pjsip_tpmgr_get_state_cb( 1530 const pjsip_tpmgr *mgr); 1531 1532 1533 /** 1534 * Add a listener to the specified transport for transport state notification. 1535 * 1536 * @param tp The transport. 1537 * @param cb Callback to be called to notify listener about transport 1538 * state changing. 1539 * @param user_data The user data. 1540 * @param key Output key, used to remove this listener. 1541 * 1542 * @return PJ_SUCCESS on success, or the appropriate error code. 1543 */ 1544 PJ_DECL(pj_status_t) pjsip_transport_add_state_listener ( 1545 pjsip_transport *tp, 1546 pjsip_tp_state_callback cb, 1547 void *user_data, 1548 pjsip_tp_state_listener_key **key); 1549 1550 1551 /** 1552 * Remove a listener from the specified transport for transport state 1553 * notification. 1554 * 1555 * @param tp The transport. 1556 * @param key The listener key. 1557 * @param user_data The user data, for validation purpose. 1558 * 1559 * @return PJ_SUCCESS on success, or the appropriate error code. 1560 */ 1561 PJ_DECL(pj_status_t) pjsip_transport_remove_state_listener ( 1562 pjsip_transport *tp, 1563 pjsip_tp_state_listener_key *key, 1564 const void *user_data); 1565 1566 1567 /** 1568 * Structure of dropped received data. 1569 */ 1570 typedef struct pjsip_tp_dropped_data 1571 { 1572 /** 1573 * The transport receiving the data. 1574 */ 1575 pjsip_transport *tp; 1576 1577 /** 1578 * The data. 1579 */ 1580 void *data; 1581 1582 /** 1583 * The data length. 1584 * If the status field below indicates an invalid SIP message 1585 * (PJSIP_EINVALIDMSG) and application detects a SIP message 1586 * at position p, it can pass the data back to PJSIP to be processed 1587 * by setting the len to p. This can be useful for apps which 1588 * wishes to use the same transport for SIP signalling and non-SIP 1589 * purposes (such as SIP outbound using STUN message). 1590 */ 1591 pj_size_t len; 1592 1593 /** 1594 * The status or reason of drop. For example, a leading newlines (common 1595 * keep-alive packet) will be dropped with status PJ_EIGNORED, an invalid 1596 * SIP message will have status PJSIP_EINVALIDMSG, a SIP message overflow 1597 * will have status PJSIP_ERXOVERFLOW. 1598 */ 1599 pj_status_t status; 1600 1601 } pjsip_tp_dropped_data; 1602 1603 1604 /** 1605 * Type of callback to data dropping notifications. 1606 * 1607 * @param data The dropped data. 1608 */ 1609 typedef void (*pjsip_tp_on_rx_dropped_cb)(pjsip_tp_dropped_data *data); 1610 1611 1612 /** 1613 * Set callback of data dropping. The caller will be notified whenever any 1614 * received data is dropped (due to leading newlines or keep-alive packet or 1615 * invalid SIP message). This callback can be useful for application, 1616 * for example, to implement custom keep-alive mechanism or connection 1617 * availability detection. 1618 * 1619 * @param mgr Transport manager. 1620 * @param cb The callback function, set to NULL to reset the callback. 1621 * 1622 * @return PJ_SUCCESS on success, or the appropriate error code. 1623 */ 1624 PJ_DECL(pj_status_t) pjsip_tpmgr_set_drop_data_cb(pjsip_tpmgr *mgr, 1625 pjsip_tp_on_rx_dropped_cb cb); 1626 1627 1628 /** 1629 * @} 1630 */ 1631 1632 1633 PJ_END_DECL 1634 1635 #endif /* __PJSIP_SIP_TRANSPORT_H__ */ 1636 1637