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_DIALOG_H__ 21 #define __PJSIP_SIP_DIALOG_H__ 22 23 24 /** 25 * @file sip_dialog.h 26 * @brief SIP Dialog abstraction 27 */ 28 29 #include <pjsip/sip_msg.h> 30 #include <pjsip/sip_auth.h> 31 #include <pjsip/sip_errno.h> 32 #include <pjsip/sip_transport.h> 33 #include <pjsip/sip_util.h> 34 #include <pj/sock.h> 35 #include <pj/assert.h> 36 37 38 /** 39 * @defgroup PJSIP_DIALOG Base Dialog 40 * @ingroup PJSIP_UA 41 * @brief The base dialog framework to support dialog usages. 42 * @{ 43 * 44 * The base dialog framework provides management for base dialog 45 * properties such as <b>From</b> header, <b>To</b> header, <b>CSeq</b> 46 * sequencing, <b>Call-ID</b> header, <b>Contact</b> header management, 47 * dialog <b>route-set</b> management, and common <b>authentication</b>. 48 * This basic dialog functionality will be shared by all <b>dialog 49 * usages</b> of a particular dialog. 50 * 51 * More detailed information is explained in 52 * <A HREF="/docs.htm">PJSIP Developer's Guide</A> 53 * PDF document, and readers are encouraged to read the document to 54 * get the concept behind dialog, dialog usages, and INVITE sessions. 55 * 56 * Application MUST initialize the user agent layer module by calling 57 * #pjsip_ua_init_module() before using any of the dialog API, and link 58 * the application with with <b>pjsip-core</b> library. 59 */ 60 61 PJ_BEGIN_DECL 62 63 64 /* Deprecated API pjsip_dlg_create_uas() due to a fatal bug of possible 65 * premature dialog destroy. Application should not change this setting, 66 * unless it uses single worker thread. 67 * See also https://trac.pjsip.org/repos/ticket/1902. 68 */ 69 #ifndef DEPRECATED_FOR_TICKET_1902 70 # define DEPRECATED_FOR_TICKET_1902 1 71 #endif 72 73 /** 74 * This structure is used to describe dialog's participants, which in this 75 * case is local party (i.e. us) and remote party. 76 */ 77 typedef struct pjsip_dlg_party 78 { 79 pjsip_fromto_hdr *info; /**< From/To header, inc tag. */ 80 pj_str_t info_str; /**< String rep of info header. */ 81 pj_uint32_t tag_hval; /**< Hashed value of the tag. */ 82 pjsip_contact_hdr *contact; /**< Contact header. */ 83 pj_int32_t first_cseq;/**< First CSeq seen. */ 84 pj_int32_t cseq; /**< Next sequence number. */ 85 } pjsip_dlg_party; 86 87 88 /** 89 * Dialog state. 90 */ 91 typedef enum pjsip_dialog_state 92 { 93 /** Dialog is not established. */ 94 PJSIP_DIALOG_STATE_NULL, 95 96 /** Dialog has been established (probably early) */ 97 PJSIP_DIALOG_STATE_ESTABLISHED 98 } pjsip_dialog_state; 99 100 101 /** 102 * Dialog capability status. 103 */ 104 typedef enum pjsip_dialog_cap_status 105 { 106 /** Capability is unsupported. */ 107 PJSIP_DIALOG_CAP_UNSUPPORTED = 0, 108 109 /** Capability is supported */ 110 PJSIP_DIALOG_CAP_SUPPORTED = 1, 111 112 /** 113 * Unknown capability status. This is usually because we lack the 114 * capability info which is retrieved from capability header specified 115 * in the dialog messages. 116 */ 117 PJSIP_DIALOG_CAP_UNKNOWN = 2 118 } pjsip_dialog_cap_status; 119 120 121 /** 122 * This structure describes the dialog structure. Application MUST NOT 123 * try to SET the values here directly, but instead it MUST use the 124 * appropriate dialog API. The dialog declaration only needs to be made 125 * visible because other PJSIP modules need to see it (e.g. INVITE session, 126 * the event framework, etc.). 127 * 128 * Application MAY READ the dialog contents directly after it acquires 129 * dialog lock. 130 * 131 * To acquire dialog lock, use #pjsip_dlg_inc_lock(), and to release it, 132 * use #pjsip_dlg_dec_lock(). DO NOT USE pj_mutex_lock()/pj_mutex_unlock() 133 * on the dialog's mutex directly, because this will not protect against 134 * dialog being destroyed. 135 */ 136 struct pjsip_dialog 137 { 138 /** The dialog set list. */ 139 PJ_DECL_LIST_MEMBER(pjsip_dialog); 140 141 /* Dialog's system properties. */ 142 char obj_name[PJ_MAX_OBJ_NAME]; /**< Standard id. */ 143 pj_pool_t *pool; /**< Dialog's pool. */ 144 pjsip_user_agent *ua; /**< User agent instance. */ 145 pjsip_endpoint *endpt; /**< Endpoint instance. */ 146 pj_grp_lock_t *grp_lock_; /**< Dialog's grp lock. Do not call!! 147 Use pjsip_dlg_inc_lock() instead! */ 148 149 /** The dialog set which this dialog belongs (opaque type). */ 150 void *dlg_set; 151 152 /* Dialog's session properties. */ 153 pjsip_dialog_state state; /**< Dialog state. */ 154 pjsip_uri *target; /**< Current target. */ 155 pjsip_target_set target_set; /**< Target set, for UAC only. */ 156 pjsip_hdr inv_hdr; /**< Headers from hparam in dest URL */ 157 pjsip_dlg_party local; /**< Local party info. */ 158 pjsip_dlg_party remote; /**< Remote party info. */ 159 pjsip_hdr rem_cap_hdr;/**< List of remote capability header. */ 160 pjsip_role_e role; /**< Initial role. */ 161 pj_bool_t uac_has_2xx;/**< UAC has received 2xx response? */ 162 pj_bool_t secure; /**< Use secure transport? */ 163 pj_bool_t add_allow; /**< Add Allow header in requests? */ 164 pjsip_cid_hdr *call_id; /**< Call-ID header. */ 165 pjsip_route_hdr route_set; /**< Route set. */ 166 pj_bool_t route_set_frozen; /**< Route set has been set. */ 167 pjsip_auth_clt_sess auth_sess; /**< Client authentication session. */ 168 pj_str_t initial_dest;/**< Initial destination host. */ 169 170 /** Session counter. */ 171 int sess_count; /**< Number of sessions. */ 172 173 /** Transaction counter. */ 174 int tsx_count; /**< Number of pending transactions. */ 175 176 /** Transport selector. */ 177 pjsip_tpselector tp_sel; 178 179 /* Dialog usages. */ 180 unsigned usage_cnt; /**< Number of registered usages. */ 181 pjsip_module *usage[PJSIP_MAX_MODULE]; /**< Array of usages, 182 priority sorted */ 183 184 /** Module specific data. */ 185 void *mod_data[PJSIP_MAX_MODULE]; /**< Module data. */ 186 187 /** 188 * If via_addr is set, it will be used as the "sent-by" field of the 189 * Via header for outgoing requests as long as the request uses via_tp 190 * transport. Normally application should not use or access these fields. 191 */ 192 pjsip_host_port via_addr; /**< Via address. */ 193 const void *via_tp; /**< Via transport. */ 194 }; 195 196 /** 197 * The parameter for \a pjsip_dlg_create_uac2(). 198 */ 199 typedef struct pjsip_dlg_create_uac_param { 200 /** 201 * The user agent module instance. 202 */ 203 pjsip_user_agent *ua; 204 205 /** 206 * Dialog local URI (i.e. From header). 207 */ 208 pj_str_t local_uri; 209 210 /** 211 * Optional dialog local Contact to be put as Contact header value, 212 * hence the format must follow RFC 3261 Section 20.10: 213 * When the header field value contains a display name, the URI including 214 * all URI parameters is enclosed in "<" and ">". If no "<" and ">" are 215 * present, all parameters after the URI are header parameters, not 216 * URI parameters. The display name can be tokens, or a quoted string, 217 * if a larger character set is desired. If this argument is NULL, 218 * the Contact will be taken from the local URI. 219 */ 220 pj_str_t local_contact; 221 222 /** 223 * Dialog remote URI (i.e. To header). 224 */ 225 pj_str_t remote_uri; 226 227 /** 228 * Optional initial remote target. If this argument is NULL, the initial 229 * target will be set to remote URI. 230 */ 231 pj_str_t target; 232 233 /** 234 * Optional group lock to use by this dialog. If the value is NULL, 235 * the dialog will create its own group lock. 236 */ 237 pj_grp_lock_t *grp_lock; 238 239 } pjsip_dlg_create_uac_param; 240 241 242 /** 243 * This utility function returns PJ_TRUE if the specified method is a 244 * dialog creating request. This method property is used to determine 245 * whether Contact header should be included in outgoing request. 246 * 247 * @param m The SIP method. 248 * 249 * @return PJ_TRUE if the method creates a dialog. 250 */ 251 PJ_DECL(pj_bool_t) pjsip_method_creates_dialog(const pjsip_method *m); 252 253 /** 254 * Create a new dialog and return the instance in p_dlg parameter. 255 * After creating the dialog, application can add modules as dialog usages 256 * by calling #pjsip_dlg_add_usage(). 257 * 258 * If the request has To tag parameter, dialog's local tag will be initialized 259 * from this value. Otherwise a globally unique id generator will be invoked to 260 * create dialog's local tag. 261 * 262 * This function also initializes the dialog's route set based on the 263 * Record-Route headers in the request, if present. 264 * 265 * Note that initially, the session count in the dialog will be initialized 266 * to zero. 267 * 268 * @param ua The user agent module instance. 269 * @param local_uri Dialog local URI (i.e. From header). 270 * @param local_contact Optional dialog local Contact to be put as Contact 271 * header value, hence the format must follow 272 * RFC 3261 Section 20.10: 273 * When the header field value contains a display 274 * name, the URI including all URI parameters is 275 * enclosed in "<" and ">". If no "<" and ">" are 276 * present, all parameters after the URI are header 277 * parameters, not URI parameters. The display name 278 * can be tokens, or a quoted string, if a larger 279 * character set is desired. 280 * If this argument is NULL, the Contact will be taken 281 * from the local URI. 282 * @param remote_uri Dialog remote URI (i.e. To header). 283 * @param target Optional initial remote target. If this argument 284 * is NULL, the initial target will be set to 285 * remote URI. 286 * @param p_dlg Pointer to receive the dialog. 287 * 288 * @return PJ_SUCCESS on success. 289 */ 290 PJ_DECL(pj_status_t) pjsip_dlg_create_uac( pjsip_user_agent *ua, 291 const pj_str_t *local_uri, 292 const pj_str_t *local_contact, 293 const pj_str_t *remote_uri, 294 const pj_str_t *target, 295 pjsip_dialog **p_dlg); 296 297 /** 298 * Variant of pjsip_dlg_create_uac() with additional parameter to specify 299 * the group lock to use. Group lock can be used to synchronize locking 300 * among several objects to prevent deadlock, and to synchronize the 301 * lifetime of objects sharing the same group lock. 302 * 303 * See \a pjsip_dlg_create_uac() for general info about this function. 304 * 305 * @param param The parameter, refer to 306 * \a pjsip_dlg_create_uac_param 307 * @param p_dlg Pointer to receive the dialog. 308 * 309 * @return PJ_SUCCESS on success. 310 */ 311 PJ_DECL(pj_status_t) pjsip_dlg_create_uac2( 312 const pjsip_dlg_create_uac_param *create_param, 313 pjsip_dialog **p_dlg); 314 315 316 #if !DEPRECATED_FOR_TICKET_1902 317 /** 318 * Initialize UAS dialog from the information found in the incoming request 319 * that creates a dialog (such as INVITE, REFER, or SUBSCRIBE), and set the 320 * local Contact to contact. If contact is not specified, the local contact 321 * is initialized from the URI in the To header in the request. 322 * 323 * This function will also create UAS transaction for the incoming request, 324 * and associate the transaction to the rdata. Application can query the 325 * transaction used to handle this request by calling #pjsip_rdata_get_tsx() 326 * after this function returns. 327 * 328 * Note that initially, the session count in the dialog will be initialized 329 * to zero. 330 * 331 * 332 * @param ua The user agent module instance. 333 * @param rdata The incoming request that creates the dialog, 334 * such as INVITE, SUBSCRIBE, or REFER. 335 * @param contact Optional dialog local Contact to be put as Contact 336 * header value, hence the format must follow 337 * RFC 3261 Section 20.10: 338 * When the header field value contains a display 339 * name, the URI including all URI parameters is 340 * enclosed in "<" and ">". If no "<" and ">" are 341 * present, all parameters after the URI are header 342 * parameters, not URI parameters. The display name 343 * can be tokens, or a quoted string, if a larger 344 * character set is desired. 345 * If this argument is NULL, the local contact will be 346 * initialized from the value of To header in the 347 * request. 348 * @param p_dlg Pointer to receive the dialog. 349 * 350 * @return PJ_SUCCESS on success. 351 */ 352 PJ_DECL(pj_status_t) pjsip_dlg_create_uas( pjsip_user_agent *ua, 353 pjsip_rx_data *rdata, 354 const pj_str_t *contact, 355 pjsip_dialog **p_dlg); 356 #endif 357 358 359 /** 360 * Initialize UAS dialog from the information found in the incoming request 361 * that creates a dialog (such as INVITE, REFER, or SUBSCRIBE), and set the 362 * local Contact to contact. If contact is not specified, the local contact 363 * is initialized from the URI in the To header in the request. 364 * 365 * This function will also create UAS transaction for the incoming request, 366 * and associate the transaction to the rdata. Application can query the 367 * transaction used to handle this request by calling #pjsip_rdata_get_tsx() 368 * after this function returns. 369 * 370 * Note that initially, the session count in the dialog will be initialized 371 * to 1 (one), and the dialog is locked. Application needs to explicitly call 372 * #pjsip_dlg_dec_lock() to release the lock and decrease the session count. 373 * 374 * 375 * @param ua The user agent module instance. 376 * @param rdata The incoming request that creates the dialog, 377 * such as INVITE, SUBSCRIBE, or REFER. 378 * @param contact Optional dialog local Contact to be put as Contact 379 * header value, hence the format must follow 380 * RFC 3261 Section 20.10: 381 * When the header field value contains a display 382 * name, the URI including all URI parameters is 383 * enclosed in "<" and ">". If no "<" and ">" are 384 * present, all parameters after the URI are header 385 * parameters, not URI parameters. The display name 386 * can be tokens, or a quoted string, if a larger 387 * character set is desired. 388 * If this argument is NULL, the local contact will be 389 * initialized from the value of To header in the 390 * request. 391 * @param p_dlg Pointer to receive the dialog. 392 * 393 * @return PJ_SUCCESS on success. 394 */ 395 PJ_DECL(pj_status_t) 396 pjsip_dlg_create_uas_and_inc_lock( pjsip_user_agent *ua, 397 pjsip_rx_data *rdata, 398 const pj_str_t *contact, 399 pjsip_dialog **p_dlg); 400 401 402 /** 403 * Lock/bind dialog to a specific transport/listener. This is optional, 404 * as normally transport will be selected automatically based on the 405 * destination of messages upon resolver completion. When the dialog is 406 * explicitly bound to the specific transport/listener, all transactions 407 * originated by this dialog will use the specified transport/listener 408 * when sending outgoing requests. 409 * 410 * Note that this doesn't affect the Contact header generated by this 411 * dialog. Application must manually update the Contact header if 412 * necessary, to adjust the address according to the transport being 413 * selected. 414 * 415 * @param dlg The dialog instance. 416 * @param sel Transport selector containing the specification of 417 * transport or listener to be used by this dialog 418 * to send requests. 419 * 420 * @return PJ_SUCCESS on success, or the appropriate error code. 421 */ 422 PJ_DECL(pj_status_t) pjsip_dlg_set_transport(pjsip_dialog *dlg, 423 const pjsip_tpselector *sel); 424 425 426 /** 427 * Set the "sent-by" field of the Via header for outgoing requests. 428 * 429 * @param dlg The dialog instance. 430 * @param via_addr Set via_addr to use for the Via header or NULL to use 431 * the transport's published name. 432 * @param via_tp via_addr will only be used if we are using via_tp 433 * transport. 434 * 435 * @return PJ_SUCCESS on success. 436 */ 437 PJ_DECL(pj_status_t) pjsip_dlg_set_via_sent_by(pjsip_dialog *dlg, 438 pjsip_host_port *via_addr, 439 pjsip_transport *via_tp); 440 441 442 /** 443 * Create a new (forked) dialog on receipt on forked response in rdata. 444 * The new dialog will be created from original_dlg, except that it will have 445 * new remote tag as copied from the To header in the response. Upon return, 446 * the new_dlg will have been registered to the user agent. Applications just 447 * need to add modules as dialog's usages. 448 * 449 * Note that initially, the session count in the dialog will be initialized 450 * to zero. 451 * 452 * @param original_dlg The original UAC dialog. 453 * @param rdata The incoming forked response message. 454 * @param new_dlg Pointer to receive the new dialog. 455 * 456 * @return PJ_SUCCESS on success. 457 */ 458 PJ_DECL(pj_status_t) pjsip_dlg_fork(const pjsip_dialog *original_dlg, 459 const pjsip_rx_data *rdata, 460 pjsip_dialog **new_dlg ); 461 462 /** 463 * Forcefully terminate the dialog. Application can only call this function 464 * when there is no session associated to the dialog. If there are sessions 465 * that use this dialog, this function will refuse to terminate the dialog. 466 * For this case, application MUST call the appropriate termination function 467 * for each dialog session (e.g. #pjsip_inv_terminate() to terminate INVITE 468 * session). 469 * 470 * @param dlg The dialog. 471 * 472 * @return PJ_SUCCESS if dialog has been terminated. 473 */ 474 PJ_DECL(pj_status_t) pjsip_dlg_terminate( pjsip_dialog *dlg ); 475 476 477 /** 478 * Set dialog's initial route set to route_set list. This can only be called 479 * for UAC dialog, before any request is sent. After dialog has been 480 * established, the route set can not be changed. 481 * 482 * For UAS dialog, the route set will be initialized in 483 * pjsip_dlg_create_uas_and_inc_lock() from the Record-Route headers in 484 * the incoming request. 485 * 486 * The route_set argument is standard list of Route headers (i.e. with 487 * sentinel). 488 * 489 * @param dlg The UAC dialog. 490 * @param route_set List of Route header. 491 * 492 * @return PJ_SUCCESS on success. 493 */ 494 PJ_DECL(pj_status_t) pjsip_dlg_set_route_set( pjsip_dialog *dlg, 495 const pjsip_route_hdr *route_set ); 496 497 /** 498 * Increment the number of sessions in the dialog. Note that initially 499 * (after created) the dialog has the session counter set to zero. 500 * 501 * @param dlg The dialog. 502 * @param mod The module that increments the session counter. 503 * 504 * @return PJ_SUCCESS on success. 505 */ 506 PJ_DECL(pj_status_t) pjsip_dlg_inc_session( pjsip_dialog *dlg, 507 pjsip_module *mod); 508 509 510 /** 511 * Decrement the number of sessions in the dialog. Once the session counter 512 * reach zero and there is no pending transaction, the dialog will be 513 * destroyed. Note that this function may destroy the dialog immediately 514 * if there is no pending transaction when this function is called. 515 * 516 * @param dlg The dialog. 517 * @param mod The module that decrements the session counter. 518 * 519 * @return PJ_SUCCESS on success. 520 */ 521 PJ_DECL(pj_status_t) pjsip_dlg_dec_session( pjsip_dialog *dlg, 522 pjsip_module *mod); 523 524 /** 525 * Add a module as dialog usage, and optionally set the module specific data. 526 * 527 * @param dlg The dialog. 528 * @param module The module to be registered as dialog usage. 529 * @param mod_data Optional arbitrary data to be attached to dialog's 530 * mod_data array at the module's index. 531 * 532 * @return PJ_SUCCESS on success. 533 */ 534 PJ_DECL(pj_status_t) pjsip_dlg_add_usage( pjsip_dialog *dlg, 535 pjsip_module *module, 536 void *mod_data ); 537 538 /** 539 * Check if the specified module has been registered as usage to the dialog. 540 * 541 * @param dlg The dialog. 542 * @param module The module. 543 * 544 * @return PJ_TRUE if the specified module is currently 545 * registered as a usage to the dialog. 546 */ 547 PJ_DECL(pj_bool_t) pjsip_dlg_has_usage(pjsip_dialog *dlg, 548 pjsip_module *module); 549 550 /** 551 * Attach module specific data to the dialog. Application can also set 552 * the value directly by accessing dlg->mod_data[module_id]. 553 * 554 * @param dlg The dialog 555 * @param mod_id The ID of the module from which the data is to be 556 * set to the dialog. 557 * @param data Arbitrary data. 558 * 559 * @return PJ_SUCCESS on success. 560 */ 561 PJ_DECL(pj_status_t) pjsip_dlg_set_mod_data( pjsip_dialog *dlg, 562 int mod_id, 563 void *data ); 564 565 /** 566 * Get module specific data previously attached to the dialog. Application 567 * can also get value directly by accessing dlg->mod_data[module_id]. 568 * 569 * @param dlg The dialog 570 * @param mod_id The ID of the module from which the data is to be 571 * retrieved from the dialog. 572 * 573 * @return The data that was previously set, or NULL. 574 */ 575 PJ_DECL(void*) pjsip_dlg_get_mod_data( pjsip_dialog *dlg, 576 int mod_id); 577 578 579 /** 580 * Lock dialog and increment session counter termporarily, to prevent it 581 * from being destroyed. 582 * 583 * @param dlg The dialog. 584 */ 585 PJ_DECL(void) pjsip_dlg_inc_lock( pjsip_dialog *dlg ); 586 587 /** 588 * Try to acquire dialog's lock, but return immediately if lock can not 589 * be acquired. 590 * 591 * @param dlg The dialog. 592 * 593 * @return PJ_SUCCESS if lock has been acquired. 594 */ 595 PJ_DECL(pj_status_t) pjsip_dlg_try_inc_lock( pjsip_dialog *dlg ); 596 597 /** 598 * Unlock dialog and decrement temporary session counter. After this function 599 * is called, dialog may be destroyed. 600 * 601 * @param dlg The dialog. 602 */ 603 PJ_DECL(void) pjsip_dlg_dec_lock( pjsip_dialog *dlg ); 604 605 /** 606 * Get the group lock for the SIP dialog. Note that prior to calling this 607 * method, it is recommended to hold reference to the dialog 608 * (e.g: call #pjsip_dlg_inc_session() or #pjsip_dlg_inc_lock()). 609 * 610 * @param dlg The dialog. 611 * 612 * @return The group lock. 613 */ 614 PJ_DECL(pj_grp_lock_t *) pjsip_dlg_get_lock( pjsip_dialog *dlg ); 615 616 617 /** 618 * Get the dialog instance in the incoming rdata. If an incoming message 619 * matches an existing dialog, the user agent must have put the matching 620 * dialog instance in the rdata, or otherwise this function will return 621 * NULL if the message didn't match any existing dialog. 622 * 623 * This function can only be called after endpoint distributes the message 624 * to the transaction layer or UA layer. In other words, application can 625 * only call this function in the context of module that runs in priority 626 * number higher than PJSIP_MOD_PRIORITY_UA_PROXY_LAYER. 627 * 628 * @param rdata Incoming message buffer. 629 * 630 * @return The dialog instance that "owns" the message. 631 */ 632 PJ_DECL(pjsip_dialog*) pjsip_rdata_get_dlg( pjsip_rx_data *rdata ); 633 634 /** 635 * Get the dialog instance for the outgoing tdata. Returns NULL if the message 636 * wasn't sent from a dialog. 637 * 638 * @param tdata Outgoing message buffer. 639 * 640 * @return The dialog instance that "owns" the message. 641 */ 642 PJ_DECL(pjsip_dialog*) pjsip_tdata_get_dlg( pjsip_tx_data *tdata ); 643 644 /** 645 * Get the associated dialog for the specified transaction, if any. 646 * 647 * @param tsx The transaction. 648 * 649 * @return The dialog instance which has been registered 650 * to the transaction as transaction user, or 651 * NULL if the transaction is outside any dialogs. 652 */ 653 PJ_DECL(pjsip_dialog*) pjsip_tsx_get_dlg( pjsip_transaction *tsx ); 654 655 656 /** 657 * Create a basic/generic request with the specified method and optionally 658 * specify the cseq. Use value -1 for cseq to have the dialog automatically 659 * put next cseq number for the request. Otherwise for some requests, 660 * e.q. CANCEL and ACK, application must put the CSeq in the original 661 * INVITE request as the parameter. 662 * 663 * This function will also put Contact header where appropriate. 664 * 665 * @param dlg The dialog instance. 666 * @param method The method of the request. 667 * @param cseq Optional CSeq, which only needs to be specified 668 * when creating ACK and CANCEL. For other requests, 669 * specify -1 to use dialog's internal counter. 670 * @param tdata Pointer to receive the request's transmit 671 * data buffer. 672 * 673 * @return PJ_SUCCESS on success. 674 */ 675 PJ_DECL(pj_status_t) pjsip_dlg_create_request( pjsip_dialog *dlg, 676 const pjsip_method *method, 677 int cseq, 678 pjsip_tx_data **tdata); 679 680 681 /** 682 * Send request message to remote peer. If the request is not an ACK request, 683 * the dialog will send the request statefully, by creating an UAC transaction 684 * and send the request with the transaction. 685 * 686 * Also when the request is not ACK or CANCEL, the dialog will increment its 687 * local cseq number and update the cseq in the request according to dialog's 688 * cseq. 689 * 690 * If p_tsx is not null, this argument will be set with the transaction 691 * instance that was used to send the request. 692 * 693 * This function will decrement the transmit data's reference counter 694 * regardless the status of the operation. 695 * 696 * @param dlg The dialog. 697 * @param tdata The request message to be sent. 698 * @param mod_data_id Optional module data index to put an optional data 699 * into the transaction. If no module data is to be 700 * attached, this value should be -1. 701 * @param mod_data Optional module data to be attached to the 702 * transaction at mod_data_id index. 703 * 704 * @return PJ_SUCCESS on success. 705 */ 706 PJ_DECL(pj_status_t) pjsip_dlg_send_request ( pjsip_dialog *dlg, 707 pjsip_tx_data *tdata, 708 int mod_data_id, 709 void *mod_data); 710 711 712 /** 713 * Create a response message for the incoming request in rdata with status 714 * code st_code and optional status text st_text. This function is different 715 * than endpoint's API #pjsip_endpt_create_response() in that the dialog 716 * function adds Contact header and Record-Routes headers in the response 717 * where appropriate. 718 * 719 * @param dlg The dialog. 720 * @param rdata The incoming request message for which the 721 * response will be created. 722 * @param st_code Status code. 723 * @param st_text Optional string for custom status reason text. 724 * @param tdata Pointer to receive the response message transmit 725 * data buffer. 726 * 727 * @return PJ_SUCCESS on success. 728 */ 729 PJ_DECL(pj_status_t) pjsip_dlg_create_response( pjsip_dialog *dlg, 730 pjsip_rx_data *rdata, 731 int st_code, 732 const pj_str_t *st_text, 733 pjsip_tx_data **tdata); 734 735 736 /** 737 * Modify previously sent response with other status code. Contact header 738 * will be added when appropriate. 739 * 740 * @param dlg The dialog. 741 * @param tdata The transmit data buffer containing response 742 * message to be modified. 743 * @param st_code New status code to be set. 744 * @param st_text Optional string for custom status reason text. 745 * 746 * @return PJ_SUCCESS on success. 747 */ 748 PJ_DECL(pj_status_t) pjsip_dlg_modify_response( pjsip_dialog *dlg, 749 pjsip_tx_data *tdata, 750 int st_code, 751 const pj_str_t *st_text); 752 753 754 /** 755 * Send response message statefully. The transaction instance MUST be the 756 * transaction that was reported on on_rx_request() callback. 757 * 758 * This function decrements the transmit data's reference counter regardless 759 * the status of the operation. 760 * 761 * @param dlg The dialog. 762 * @param tsx The UAS transaction associated with the incoming 763 * request. If the request is within a dialog, or 764 * a dialog has been created for the request that 765 * creates the dialog, application can get the 766 * transaction instance for the request by calling 767 * #pjsip_rdata_get_tsx(). 768 * @param tdata Response message to be sent. 769 * 770 * @return PJ_SUCCESS on success. 771 */ 772 PJ_DECL(pj_status_t) pjsip_dlg_send_response( pjsip_dialog *dlg, 773 pjsip_transaction *tsx, 774 pjsip_tx_data *tdata); 775 776 777 /** 778 * This composite function sends response message statefully to an incoming 779 * request message inside dialog. 780 * 781 * @param dlg The endpoint instance. 782 * @param rdata The incoming request message. 783 * @param st_code Status code of the response. 784 * @param st_text Optional status text of the response. 785 * @param hdr_list Optional header list to be added to the response. 786 * @param body Optional message body to be added to the response. 787 * 788 * @return PJ_SUCCESS if response message has successfully been 789 * sent. 790 */ 791 PJ_DECL(pj_status_t) pjsip_dlg_respond( pjsip_dialog *dlg, 792 pjsip_rx_data *rdata, 793 int st_code, 794 const pj_str_t *st_text, 795 const pjsip_hdr *hdr_list, 796 const pjsip_msg_body *body ); 797 798 799 /** 800 * Check if remote peer have the specified capability as published 801 * in the dialog messages from remote peer. 802 * 803 * Notes: 804 * - The capability \a token lookup will apply exact match, but not 805 * case-sensitive, for example: <tt>"text/html"</tt> will not match 806 * <tt>"text / html"</tt> (notice the spaces). 807 * 808 * @param dlg The dialog. 809 * @param htype The header type to be checked, which value may be: 810 * - PJSIP_H_ACCEPT 811 * - PJSIP_H_ALLOW 812 * - PJSIP_H_SUPPORTED 813 * @param hname If htype specifies PJSIP_H_OTHER, then the header name 814 * must be supplied in this argument. Otherwise the value 815 * must be set to NULL. 816 * @param token The capability token to check. For example, if \a htype 817 * is PJSIP_H_ALLOW, then \a token specifies the method 818 * names; if \a htype is PJSIP_H_SUPPORTED, then \a token 819 * specifies the extension names such as "100rel". 820 * 821 * @return PJSIP_DIALOG_CAP_SUPPORTED if the specified capability 822 * is explicitly supported, see @pjsip_dialog_cap_status 823 * for more info. 824 */ 825 PJ_DECL(pjsip_dialog_cap_status) pjsip_dlg_remote_has_cap( 826 pjsip_dialog *dlg, 827 int htype, 828 const pj_str_t *hname, 829 const pj_str_t *token); 830 831 /** 832 * Get the specified capability header from the remote capability headers 833 * stored in the dialog. 834 * 835 * @param dlg The dialog. 836 * @param htype The header type to be retrieved, which value may be: 837 * - PJSIP_H_ACCEPT 838 * - PJSIP_H_ALLOW 839 * - PJSIP_H_SUPPORTED 840 * @param hname If htype specifies PJSIP_H_OTHER, then the header name 841 * must be supplied in this argument. Otherwise the value 842 * must be set to NULL. 843 * 844 * @return The appropriate header, or NULL if the header is not 845 * available. 846 */ 847 PJ_DECL(const pjsip_hdr*) pjsip_dlg_get_remote_cap_hdr(pjsip_dialog *dlg, 848 int htype, 849 const pj_str_t *hname); 850 851 /** 852 * Set remote capability from a SIP header containing array of capability 853 * tags/values. 854 * 855 * @param dlg The dialog. 856 * @param cap_hdr The SIP header. 857 * 858 * @return PJ_SUCCESS when successful, otherwise the appropriate 859 * error code will be returned. 860 */ 861 PJ_DECL(pj_status_t) pjsip_dlg_set_remote_cap_hdr( 862 pjsip_dialog *dlg, 863 const pjsip_generic_array_hdr *cap_hdr); 864 865 /** 866 * Remove a remote capability header. 867 * 868 * @param dlg The dialog. 869 * @param htype The header type to be removed, which value may be: 870 * - PJSIP_H_ACCEPT 871 * - PJSIP_H_ALLOW 872 * - PJSIP_H_SUPPORTED 873 * @param hname If htype specifies PJSIP_H_OTHER, then the header name 874 * must be supplied in this argument. Otherwise the value 875 * must be set to NULL. 876 * 877 * @return PJ_SUCCESS when successful, otherwise the appropriate 878 * error code will be returned. 879 */ 880 PJ_DECL(pj_status_t) pjsip_dlg_remove_remote_cap_hdr(pjsip_dialog *dlg, 881 int htype, 882 const pj_str_t *hname); 883 884 /** 885 * Update remote capabilities from a received message. The header types 886 * to be updated from the message will only be \a PJSIP_H_ACCEPT, 887 * \a PJSIP_H_ALLOW, and \a PJSIP_H_SUPPORTED. 888 * 889 * @param dlg The dialog. 890 * @param msg The received message. 891 * @param strict If this is set to PJ_TRUE, any header types missing 892 * from the message will cause removal of existing 893 * header types in the capability list. Otherwise, the 894 * capability list will not be modified when any header 895 * type is missing. 896 * 897 * @return PJ_SUCCESS when successful, otherwise the appropriate 898 * error code will be returned. 899 */ 900 PJ_DECL(pj_status_t) pjsip_dlg_update_remote_cap(pjsip_dialog *dlg, 901 const pjsip_msg *msg, 902 pj_bool_t strict); 903 904 905 906 /** 907 * @} 908 */ 909 910 /* 911 * Internal (called by sip_ua_layer.c) 912 */ 913 914 /* Receives transaction event (called by user_agent module) */ 915 void pjsip_dlg_on_tsx_state( pjsip_dialog *dlg, 916 pjsip_transaction *tsx, 917 pjsip_event *e ); 918 919 void pjsip_dlg_on_rx_request( pjsip_dialog *dlg, 920 pjsip_rx_data *rdata ); 921 922 void pjsip_dlg_on_rx_response( pjsip_dialog *dlg, 923 pjsip_rx_data *rdata ); 924 925 926 927 PJ_END_DECL 928 929 930 #endif /* __PJSIP_SIP_DIALOG_H__ */ 931 932