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