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 __SIP_INVITE_SESSION_H__ 21 #define __SIP_INVITE_SESSION_H__ 22 23 /** 24 * @file sip_inv.h 25 * @brief INVITE sessions 26 */ 27 28 29 #include <pjsip/sip_dialog.h> 30 #include <pjmedia/sdp_neg.h> 31 32 33 /** 34 * @defgroup PJSIP_HIGH_UA User Agent Library 35 * @brief Mid-level User Agent Library. 36 * 37 * This is the high level user agent library, which consists of: 38 * - @ref PJSIP_INV, to encapsulate INVITE sessions and SDP 39 * negotiation in the session, 40 * - @ref PJSUA_REGC, high level client registration API, and 41 * - @ref PJSUA_XFER. 42 * 43 * More detailed information is explained in 44 * <A HREF="/docs.htm">PJSIP Developer's Guide</A> 45 * PDF document, and readers are encouraged to read the document to 46 * get the concept behind dialog, dialog usages, and INVITE sessions. 47 * 48 * The User Agent Library is implemented in <b>pjsip-ua</b> static 49 * library. 50 */ 51 52 /** 53 * @defgroup PJSIP_INV INVITE Session 54 * @ingroup PJSIP_HIGH_UA 55 * @brief Provides INVITE session management. 56 * @{ 57 * 58 * The INVITE session uses the @ref PJSIP_DIALOG framework to manage 59 * the underlying dialog, and is one type of usages that can use 60 * a particular dialog instance (other usages are event subscription, 61 * discussed in @ref PJSIP_EVENT_NOT). The INVITE session manages 62 * the life-time of the session, and also manages the SDP negotiation. 63 * 64 * Application must link with <b>pjsip-ua</b> static library to use this API. 65 * 66 * More detailed information is explained in 67 * <A HREF="/docs.htm">PJSIP Developer's Guide</A> 68 * PDF document, and readers are encouraged to read the document to 69 * get the concept behind dialog, dialog usages, and INVITE sessions. 70 * 71 * The INVITE session does NOT manage media. If application wants to 72 * use API that encapsulates both signaling and media in a very easy 73 * to use API, it can use @ref PJSUA_LIB for this purpose. 74 */ 75 76 PJ_BEGIN_DECL 77 78 79 /** 80 * @see pjsip_inv_session 81 */ 82 typedef struct pjsip_inv_session pjsip_inv_session; 83 84 85 /** 86 * This enumeration describes invite session state. 87 */ 88 typedef enum pjsip_inv_state 89 { 90 PJSIP_INV_STATE_NULL, /**< Before INVITE is sent or received */ 91 PJSIP_INV_STATE_CALLING, /**< After INVITE is sent */ 92 PJSIP_INV_STATE_INCOMING, /**< After INVITE is received. */ 93 PJSIP_INV_STATE_EARLY, /**< After response with To tag. */ 94 PJSIP_INV_STATE_CONNECTING, /**< After 2xx is sent/received. */ 95 PJSIP_INV_STATE_CONFIRMED, /**< After ACK is sent/received. */ 96 PJSIP_INV_STATE_DISCONNECTED, /**< Session is terminated. */ 97 } pjsip_inv_state; 98 99 /** 100 * Structure to hold parameters when calling the callback 101 * #on_rx_offer2(). 102 */ 103 struct pjsip_inv_on_rx_offer_cb_param 104 { 105 const pjmedia_sdp_session *offer; /** Remote offer. */ 106 const pjsip_rx_data *rdata; /** The received request. */ 107 }; 108 109 110 /** 111 * This structure contains callbacks to be registered by application to 112 * receieve notifications from the framework about various events in 113 * the invite session. 114 */ 115 typedef struct pjsip_inv_callback 116 { 117 /** 118 * This callback is called when the invite sesion state has changed. 119 * Application should inspect the session state (inv_sess->state) to get 120 * the current state of the session. 121 * 122 * This callback is mandatory. 123 * 124 * @param inv The invite session. 125 * @param e The event which has caused the invite session's 126 * state to change. 127 */ 128 void (*on_state_changed)(pjsip_inv_session *inv, pjsip_event *e); 129 130 /** 131 * This callback is called when the invite usage module has created 132 * a new dialog and invite because of forked outgoing request. 133 * 134 * Currently the invite session does not create a new dialog in 135 * forking scenario, so this callback will never be invoked. 136 * 137 * @param inv The new invite session. 138 * @param e The event which has caused the dialog to fork. 139 * The type of this event can be either 140 * PJSIP_EVENT_RX_MSG or PJSIP_EVENT_RX_200_MSG. 141 */ 142 void (*on_new_session)(pjsip_inv_session *inv, pjsip_event *e); 143 144 /** 145 * This callback is called whenever any transactions within the session 146 * has changed their state. Application MAY implement this callback, 147 * e.g. to monitor the progress of an outgoing request, or to send 148 * response to unhandled incoming request (such as INFO). 149 * 150 * This callback is optional. 151 * 152 * @param inv The invite session. 153 * @param tsx The transaction, which state has changed. 154 * @param e The event which has caused the transation state's 155 * to change. 156 */ 157 void (*on_tsx_state_changed)(pjsip_inv_session *inv, 158 pjsip_transaction *tsx, 159 pjsip_event *e); 160 161 /** 162 * This callback is called when the invite session has received 163 * new offer from peer. Application can inspect the remote offer 164 * in "offer", and set the SDP answer with #pjsip_inv_set_sdp_answer(). 165 * When the application sends a SIP message to send the answer, 166 * this SDP answer will be negotiated with the offer, and the result 167 * will be sent with the SIP message. 168 * 169 * Note: if callback #on_rx_offer2() is implemented, this callback will 170 * not be called. 171 * 172 * @param inv The invite session. 173 * @param offer Remote offer. 174 */ 175 void (*on_rx_offer)(pjsip_inv_session *inv, 176 const pjmedia_sdp_session *offer); 177 178 /** 179 * This callback is called when the invite session has received 180 * new offer from peer. Variant of #on_rx_offer() callback. 181 * 182 * @param inv The invite session. 183 * @param param The callback parameters. 184 */ 185 void (*on_rx_offer2)(pjsip_inv_session *inv, 186 struct pjsip_inv_on_rx_offer_cb_param *param); 187 188 /** 189 * This callback is optional, and is called when the invite session has 190 * received a re-INVITE from the peer. It will be called after 191 * on_rx_offer() callback and works only for re-INVITEs. It allows more 192 * fine-grained control over the response to a re-INVITE, e.g. sending 193 * a provisional response first. Application can return PJ_SUCCESS and 194 * send a reply using the function #pjsip_inv_initial_answer() or 195 * #pjsip_inv_answer(), as with the initial INVITE. If application 196 * returns non-PJ_SUCCESS, it needs to set the SDP answer with 197 * #pjsip_inv_set_sdp_answer() and the re-INVITE will be answered 198 * automatically. 199 * 200 * Remarks: Application may need to monitor on_tsx_state_changed() 201 * callback to check whether the re-INVITE is already answered 202 * automatically with 487 due to being cancelled. 203 * 204 * @param inv The invite session. 205 * @param offer Remote offer. 206 * @param rdata The received re-INVITE request. 207 * 208 * @return - PJ_SUCCESS: application will answer the re-INVITE 209 * manually 210 * - non-PJ_SUCCESS: answer the re-INVITE automatically 211 * using the SDP set via #pjsip_inv_set_sdp_answer() 212 */ 213 pj_status_t (*on_rx_reinvite)(pjsip_inv_session *inv, 214 const pjmedia_sdp_session *offer, 215 pjsip_rx_data *rdata); 216 217 /** 218 * This callback is optional, and it is used to ask the application 219 * to create a fresh offer, when the invite session has received 220 * re-INVITE without offer. This offer then will be sent in the 221 * 200/OK response to the re-INVITE request. 222 * 223 * If application doesn't implement this callback, the invite session 224 * will send the currently active SDP as the offer. 225 * 226 * @param inv The invite session. 227 * @param p_offer Pointer to receive the SDP offer created by 228 * application. 229 */ 230 void (*on_create_offer)(pjsip_inv_session *inv, 231 pjmedia_sdp_session **p_offer); 232 233 /** 234 * This callback is called after SDP offer/answer session has completed. 235 * The status argument specifies the status of the offer/answer, 236 * as returned by pjmedia_sdp_neg_negotiate(). 237 * 238 * This callback is optional (from the point of view of the framework), 239 * but all useful applications normally need to implement this callback. 240 * 241 * @param inv The invite session. 242 * @param status The negotiation status. 243 */ 244 void (*on_media_update)(pjsip_inv_session *inv_ses, 245 pj_status_t status); 246 247 /** 248 * This callback is called when the framework needs to send 249 * ACK request after it receives incoming 2xx response for 250 * INVITE. It allows application to manually handle the 251 * transmission of ACK request, which is required by some 3PCC 252 * scenarios. If this callback is not implemented, the framework 253 * will handle the ACK transmission automatically. 254 * 255 * When this callback is overridden, application may delay the 256 * sending of the ACK request (for example, when it needs to 257 * wait for answer from the other call leg, in 3PCC scenarios). 258 * 259 * Application MUST create the ACK request using pjsip_inv_create_ack() 260 * and send it using pjsip_inv_send_msg(). 261 * 262 * Once it has sent the ACK request, the framework will keep 263 * this ACK request in the cache. Subsequent receipt of 2xx response 264 * will not cause this callback to be called (but see exception below), 265 * and instead automatic retransmission of this ACK request from 266 * the cache will be done by the framework. 267 * Exception: if app has created the ACK but has not sent it, 268 * while it receives a retransmission of 2xx response, this callback 269 * will be called again. 270 * 271 * This callback is optional. 272 */ 273 void (*on_send_ack)(pjsip_inv_session *inv, pjsip_rx_data *rdata); 274 275 /** 276 * This callback is called when the session is about to resend the 277 * INVITE request to the specified target, following the previously 278 * received redirection response. 279 * 280 * Application may accept the redirection to the specified target 281 * (the default behavior if this callback is implemented), reject 282 * this target only and make the session continue to try the next 283 * target in the list if such target exists, stop the whole 284 * redirection process altogether and cause the session to be 285 * disconnected, or defer the decision to ask for user confirmation. 286 * 287 * This callback is optional. If this callback is not implemented, 288 * the default behavior is to NOT follow the redirection response. 289 * 290 * @param inv The invite session. 291 * @param target The current target to be tried. 292 * @param e The event that caused this callback to be called. 293 * This could be the receipt of 3xx response, or 294 * 4xx/5xx response received for the INVITE sent to 295 * subsequent targets, or NULL if this callback is 296 * called from within #pjsip_inv_process_redirect() 297 * context. 298 * 299 * @return Action to be performed for the target. Set this 300 * parameter to one of the value below: 301 * - PJSIP_REDIRECT_ACCEPT: immediately accept the 302 * redirection to this target. When set, the 303 * session will immediately resend INVITE request 304 * to the target after this callback returns. 305 * - PJSIP_REDIRECT_REJECT: immediately reject this 306 * target. The session will continue retrying with 307 * next target if present, or disconnect the call 308 * if there is no more target to try. 309 * - PJSIP_REDIRECT_STOP: stop the whole redirection 310 * process and immediately disconnect the call. The 311 * on_state_changed() callback will be called with 312 * PJSIP_INV_STATE_DISCONNECTED state immediately 313 * after this callback returns. 314 * - PJSIP_REDIRECT_PENDING: set to this value if 315 * no decision can be made immediately (for example 316 * to request confirmation from user). Application 317 * then MUST call #pjsip_inv_process_redirect() 318 * to either accept or reject the redirection upon 319 * getting user decision. 320 */ 321 pjsip_redirect_op (*on_redirected)(pjsip_inv_session *inv, 322 const pjsip_uri *target, 323 const pjsip_event *e); 324 325 } pjsip_inv_callback; 326 327 328 329 /** 330 * This enumeration shows various options that can be applied to a session. 331 * The bitmask combination of these options need to be specified when 332 * creating a session. After the dialog is established (including early), 333 * the options member of #pjsip_inv_session shows which capabilities are 334 * common in both endpoints. 335 */ 336 enum pjsip_inv_option 337 { 338 /** 339 * Indicate support for reliable provisional response extension 340 */ 341 PJSIP_INV_SUPPORT_100REL = 1, 342 343 /** 344 * Indicate support for session timer extension. 345 */ 346 PJSIP_INV_SUPPORT_TIMER = 2, 347 348 /** 349 * Indicate support for UPDATE method. This is automatically implied 350 * when creating outgoing dialog. After the dialog is established, 351 * the options member of #pjsip_inv_session shows whether peer supports 352 * this method as well. 353 */ 354 PJSIP_INV_SUPPORT_UPDATE = 4, 355 356 /** 357 * Indicate support for ICE 358 */ 359 PJSIP_INV_SUPPORT_ICE = 8, 360 361 /** 362 * Require ICE support. 363 */ 364 PJSIP_INV_REQUIRE_ICE = 16, 365 366 /** 367 * Require reliable provisional response extension. 368 */ 369 PJSIP_INV_REQUIRE_100REL = 32, 370 371 /** 372 * Require session timer extension. 373 */ 374 PJSIP_INV_REQUIRE_TIMER = 64, 375 376 /** 377 * Session timer extension will always be used even when peer doesn't 378 * support/want session timer. 379 */ 380 PJSIP_INV_ALWAYS_USE_TIMER = 128, 381 382 /** 383 * Indicate support for trickle ICE 384 */ 385 PJSIP_INV_SUPPORT_TRICKLE_ICE = 256, 386 387 /** 388 * Require trickle ICE support. 389 */ 390 PJSIP_INV_REQUIRE_TRICKLE_ICE = 512, 391 392 }; 393 394 /* Forward declaration of Session Timers */ 395 struct pjsip_timer; 396 397 /** 398 * This structure describes the invite session. 399 * 400 * Note regarding the invite session's pools. The inv_sess used to have 401 * only one pool, which is just a pointer to the dialog's pool. Ticket 402 * http://trac.pjsip.org/repos/ticket/877 has found that the memory 403 * usage will grow considerably everytime re-INVITE or UPDATE is 404 * performed. 405 * 406 * Ticket #877 then created two more memory pools for the inv_sess, so 407 * now we have three memory pools: 408 * - pool: to be used to allocate long term data for the session 409 * - pool_prov and pool_active: this is a flip-flop pools to be used 410 * interchangably during re-INVITE and UPDATE. pool_prov is 411 * "provisional" pool, used to allocate SDP offer or answer for 412 * the re-INVITE and UPDATE. Once SDP negotiation is done, the 413 * provisional pool will be made as the active pool, then the 414 * existing active pool will be reset, to release the memory 415 * back to the OS. So these pool's lifetime is synchronized to 416 * the SDP offer-answer negotiation. 417 * 418 * Higher level application such as PJSUA-LIB has been modified to 419 * make use of these flip-flop pools, i.e. by creating media objects 420 * from the provisional pool rather than from the long term pool. 421 * 422 * Other applications that want to use these pools must understand 423 * that the flip-flop pool's lifetimes are synchronized to the 424 * SDP offer-answer negotiation. 425 * 426 * The lifetime of this session is controlled by the reference counter in this 427 * structure, which is manipulated by calling #pjsip_inv_add_ref and 428 * #pjsip_inv_dec_ref. When the reference counter has reached zero, then 429 * this session will be destroyed. 430 */ 431 struct pjsip_inv_session 432 { 433 char obj_name[PJ_MAX_OBJ_NAME]; /**< Log identification */ 434 pj_pool_t *pool; /**< Long term pool. */ 435 pj_pool_t *pool_prov; /**< Provisional pool */ 436 pj_pool_t *pool_active; /**< Active/current pool*/ 437 pjsip_inv_state state; /**< Invite sess state. */ 438 pj_bool_t cancelling; /**< CANCEL requested */ 439 pj_bool_t pending_cancel; /**< Wait to send CANCEL*/ 440 pjsip_tx_data *pending_bye; /**< BYE to send later */ 441 pjsip_status_code cause; /**< Disconnect cause. */ 442 pj_str_t cause_text; /**< Cause text. */ 443 pj_bool_t notify; /**< Internal. */ 444 unsigned cb_called; /**< Cb has been called */ 445 pjsip_dialog *dlg; /**< Underlying dialog. */ 446 pjsip_role_e role; /**< Invite role. */ 447 unsigned options; /**< Options in use. */ 448 pjmedia_sdp_neg *neg; /**< Negotiator. */ 449 unsigned sdp_neg_flags; /**< SDP neg flags. */ 450 pjsip_transaction *invite_tsx; /**< 1st invite tsx. */ 451 pjsip_tx_data *invite_req; /**< Saved invite req */ 452 pjsip_tx_data *last_answer; /**< Last INVITE resp. */ 453 pjsip_tx_data *last_ack; /**< Last ACK request */ 454 pj_int32_t last_ack_cseq; /**< CSeq of last ACK */ 455 void *mod_data[PJSIP_MAX_MODULE];/**< Modules data. */ 456 struct pjsip_timer *timer; /**< Session Timers. */ 457 pj_bool_t following_fork; /**< Internal, following 458 forked media? */ 459 pj_atomic_t *ref_cnt; /**< Reference counter. */ 460 pj_bool_t updated_sdp_answer; /**< SDP answer just been 461 updated? */ 462 }; 463 464 465 /** 466 * This structure represents SDP information in a pjsip_rx_data. Application 467 * retrieve this information by calling #pjsip_rdata_get_sdp_info(). This 468 * mechanism supports multipart message body. 469 */ 470 typedef struct pjsip_rdata_sdp_info 471 { 472 /** 473 * Pointer and length of the text body in the incoming message. If 474 * the pointer is NULL, it means the message does not contain SDP 475 * body. 476 */ 477 pj_str_t body; 478 479 /** 480 * This will contain non-zero if an invalid SDP body is found in the 481 * message. 482 */ 483 pj_status_t sdp_err; 484 485 /** 486 * A parsed and validated SDP body. 487 */ 488 pjmedia_sdp_session *sdp; 489 490 } pjsip_rdata_sdp_info; 491 492 493 /** 494 * Initialize the invite usage module and register it to the endpoint. 495 * The callback argument contains pointer to functions to be called on 496 * occurences of events in invite sessions. 497 * 498 * @param endpt The endpoint instance. 499 * @param cb Callback structure. 500 * 501 * @return PJ_SUCCESS on success, or the appropriate error code. 502 */ 503 PJ_DECL(pj_status_t) pjsip_inv_usage_init(pjsip_endpoint *endpt, 504 const pjsip_inv_callback *cb); 505 506 /** 507 * Get the INVITE usage module instance. 508 * 509 * @return PJ_SUCCESS on success, or the appropriate error code. 510 */ 511 PJ_DECL(pjsip_module*) pjsip_inv_usage_instance(void); 512 513 514 /** 515 * Dump user agent contents (e.g. all dialogs). 516 */ 517 PJ_DECL(void) pjsip_inv_usage_dump(void); 518 519 520 /** 521 * Create UAC invite session for the specified dialog in dlg. 522 * 523 * @param dlg The dialog which will be used by this invite session. 524 * @param local_sdp If application has determined its media capability, 525 * it can specify the SDP here. Otherwise it can leave 526 * this to NULL, to let remote UAS specifies an offer. 527 * @param options The options argument is bitmask combination of SIP 528 * features in pjsip_inv_option enumeration. 529 * @param p_inv On successful return, the invite session will be put 530 * in this argument. 531 * 532 * @return The function will return PJ_SUCCESS if it can create 533 * the session. Otherwise the appropriate error status 534 * will be returned on failure. 535 */ 536 PJ_DECL(pj_status_t) pjsip_inv_create_uac(pjsip_dialog *dlg, 537 const pjmedia_sdp_session *local_sdp, 538 unsigned options, 539 pjsip_inv_session **p_inv); 540 541 542 /** 543 * Application SHOULD call this function upon receiving the initial INVITE 544 * request in rdata before creating the invite session (or even dialog), 545 * to verify that the invite session can handle the INVITE request. 546 * This function verifies that local endpoint is capable to handle required 547 * SIP extensions in the request (i.e. Require header) and also the media, 548 * if media description is present in the request. 549 * 550 * @param rdata The incoming INVITE request. 551 * 552 * @param options Upon calling this function, the options argument 553 * MUST contain the desired SIP extensions to be 554 * applied to the session. Upon return, this argument 555 * will contain the SIP extension that will be applied 556 * to the session, after considering the Supported, 557 * Require, and Allow headers in the request. 558 * 559 * @param sdp If local media capability has been determined, 560 * and if application wishes to verify that it can 561 * handle the media offer in the incoming INVITE 562 * request, it SHOULD specify its local media capability 563 * in this argument. 564 * If it is not specified, media verification will not 565 * be performed by this function. 566 * 567 * @param dlg If tdata is not NULL, application needs to specify 568 * how to create the response. Either dlg or endpt 569 * argument MUST be specified, with dlg argument takes 570 * precedence when both are specified. 571 * 572 * If a dialog has been created prior to calling this 573 * function, then it MUST be specified in dlg argument. 574 * Otherwise application MUST specify the endpt argument 575 * (this is useful e.g. when application wants to send 576 * the response statelessly). 577 * 578 * @param endpt If tdata is not NULL, application needs to specify 579 * how to create the response. Either dlg or endpt 580 * argument MUST be specified, with dlg argument takes 581 * precedence when both are specified. 582 * 583 * @param tdata If this argument is not NULL, this function will 584 * create the appropriate non-2xx final response message 585 * when the verification fails. 586 * 587 * @return If everything has been negotiated successfully, 588 * the function will return PJ_SUCCESS. Otherwise it 589 * will return the reason of the failure as the return 590 * code. 591 * 592 * This function is capable to create the appropriate 593 * response message when the verification has failed. 594 * If tdata is specified, then a non-2xx final response 595 * will be created and put in this argument upon return, 596 * when the verification has failed. 597 * 598 * If a dialog has been created prior to calling this 599 * function, then it MUST be specified in dlg argument. 600 * Otherwise application MUST specify the endpt argument 601 * (this is useful e.g. when application wants to send 602 * the response statelessly). 603 * 604 * @see pjsip_inv_verify_request2() 605 */ 606 PJ_DECL(pj_status_t) pjsip_inv_verify_request( pjsip_rx_data *rdata, 607 unsigned *options, 608 const pjmedia_sdp_session *sdp, 609 pjsip_dialog *dlg, 610 pjsip_endpoint *endpt, 611 pjsip_tx_data **tdata); 612 613 /** 614 * Variant of #pjsip_inv_verify_request() which allows application to specify 615 * the parsed SDP in the \a offer argument. This is useful to avoid having to 616 * re-parse the SDP in the incoming request. 617 * 618 * @see pjsip_inv_verify_request() 619 */ 620 PJ_DECL(pj_status_t) pjsip_inv_verify_request2( pjsip_rx_data *rdata, 621 unsigned *options, 622 const pjmedia_sdp_session *offer, 623 const pjmedia_sdp_session *answer, 624 pjsip_dialog *dlg, 625 pjsip_endpoint *endpt, 626 pjsip_tx_data **tdata); 627 628 /** 629 * Variant of #pjsip_inv_verify_request() which allows application not to 630 * specify the rdata (i.e. pass NULL as the rdata parameter) and specify 631 * the parsed SDP in the \a offer argument and a temporary pool in the 632 * \a tmp_pool argument. 633 * This is useful if application no longer has access to the rdata. 634 * 635 * @see pjsip_inv_verify_request() 636 */ 637 PJ_DECL(pj_status_t) pjsip_inv_verify_request3( pjsip_rx_data *rdata, 638 pj_pool_t *tmp_pool, 639 unsigned *options, 640 const pjmedia_sdp_session *offer, 641 const pjmedia_sdp_session *answer, 642 pjsip_dialog *dlg, 643 pjsip_endpoint *endpt, 644 pjsip_tx_data **tdata); 645 646 647 /** 648 * Create UAS invite session for the specified dialog in dlg. Application 649 * SHOULD call the verification function before calling this function, 650 * to ensure that it can create the session successfully. 651 * 652 * @param dlg The dialog to be used. 653 * @param rdata Application MUST specify the received INVITE request 654 * in rdata. The invite session needs to inspect the 655 * received request to see if the request contains 656 * features that it supports. 657 * @param local_sdp If application has determined its media capability, 658 * it can specify this capability in this argument. 659 * If SDP is received in the initial INVITE, the UAS 660 * capability specified in this argument doesn't have to 661 * match the received offer; the SDP negotiator is able 662 * to rearrange the media lines in the answer so that it 663 * matches the offer. 664 * @param options The options argument is bitmask combination of SIP 665 * features in pjsip_inv_option enumeration. 666 * @param p_inv Pointer to receive the newly created invite session. 667 * 668 * @return On successful, the invite session will be put in 669 * p_inv argument and the function will return PJ_SUCCESS. 670 * Otherwise the appropriate error status will be returned 671 * on failure. 672 */ 673 PJ_DECL(pj_status_t) pjsip_inv_create_uas(pjsip_dialog *dlg, 674 pjsip_rx_data *rdata, 675 const pjmedia_sdp_session *local_sdp, 676 unsigned options, 677 pjsip_inv_session **p_inv); 678 679 680 /** 681 * Add reference counter to the INVITE session. The reference counter controls 682 * the life time of the session, ie. when the counter reaches zero, then it 683 * will be destroyed. 684 * 685 * @param inv The INVITE session. 686 * @return PJ_SUCCESS if the INVITE session reference counter 687 * was increased. 688 */ 689 PJ_DECL(pj_status_t) pjsip_inv_add_ref( pjsip_inv_session *inv ); 690 691 /** 692 * Decrement reference counter of the INVITE session. 693 * When the session is no longer used, it will be destroyed and 694 * caller is informed with PJ_EGONE return status. 695 * 696 * @param inv The INVITE session. 697 * @return PJ_SUCCESS if the INVITE session reference counter 698 * was decreased. A status PJ_EGONE will be returned to 699 * inform that session is destroyed. 700 */ 701 PJ_DECL(pj_status_t) pjsip_inv_dec_ref( pjsip_inv_session *inv ); 702 703 704 /** 705 * Forcefully terminate and destroy INVITE session, regardless of 706 * the state of the session. Note that this function should only be used 707 * when there is failure in the INVITE session creation. After the 708 * invite session has been created and initialized, normally application 709 * SHOULD use #pjsip_inv_end_session() to end the INVITE session instead. 710 * 711 * Note also that this function may terminate the underlying dialog, if 712 * there are no other sessions in the dialog. 713 * 714 * @param inv The invite session. 715 * @param st_code Status code for the reason of the termination. 716 * @param notify If set to non-zero, then on_state_changed() 717 * callback will be called. 718 * 719 * @return PJ_SUCCESS if the INVITE session has been 720 * terminated. 721 */ 722 PJ_DECL(pj_status_t) pjsip_inv_terminate( pjsip_inv_session *inv, 723 int st_code, 724 pj_bool_t notify ); 725 726 727 /** 728 * Restart UAC session and prepare the session for a new initial INVITE. 729 * This function can be called for example when the application wants to 730 * follow redirection response with a new call reusing this session so 731 * that the new call will have the same Call-ID and From headers. After 732 * the session is restarted, application may create and send a new INVITE 733 * request. 734 * 735 * @param inv The invite session. 736 * @param new_offer Should be set to PJ_TRUE since the application will 737 * restart the session. 738 * 739 * @return PJ_SUCCESS on successful operation. 740 */ 741 PJ_DECL(pj_status_t) pjsip_inv_uac_restart(pjsip_inv_session *inv, 742 pj_bool_t new_offer); 743 744 745 /** 746 * Accept or reject redirection response. Application MUST call this function 747 * after it signaled PJSIP_REDIRECT_PENDING in the \a on_redirected() 748 * callback, to notify the invite session whether to accept or reject the 749 * redirection to the current target. Application can use the combination of 750 * PJSIP_REDIRECT_PENDING command in \a on_redirected() callback and this 751 * function to ask for user permission before redirecting the call. 752 * 753 * Note that if the application chooses to reject or stop redirection (by 754 * using PJSIP_REDIRECT_REJECT or PJSIP_REDIRECT_STOP respectively), the 755 * session disconnection callback will be called before this function returns. 756 * And if the application rejects the target, the \a on_redirected() callback 757 * may also be called before this function returns if there is another target 758 * to try. 759 * 760 * @param inv The invite session. 761 * @param cmd Redirection operation. The semantic of this argument 762 * is similar to the description in the \a on_redirected() 763 * callback, except that the PJSIP_REDIRECT_PENDING is 764 * not accepted here. 765 * @param e Should be set to NULL. 766 * 767 * @return PJ_SUCCESS on successful operation. 768 */ 769 PJ_DECL(pj_status_t) pjsip_inv_process_redirect(pjsip_inv_session *inv, 770 pjsip_redirect_op cmd, 771 pjsip_event *e); 772 773 774 /** 775 * Create the initial INVITE request for this session. This function can only 776 * be called for UAC session. If local media capability is specified when 777 * the invite session was created, then this function will put an SDP offer 778 * in the outgoing INVITE request. Otherwise the outgoing request will not 779 * contain SDP body. 780 * 781 * @param inv The UAC invite session. 782 * @param p_tdata The initial INVITE request will be put in this 783 * argument if it can be created successfully. 784 * 785 * @return PJ_SUCCESS if the INVITE request can be created. 786 */ 787 PJ_DECL(pj_status_t) pjsip_inv_invite( pjsip_inv_session *inv, 788 pjsip_tx_data **p_tdata ); 789 790 791 /** 792 * Create the initial response message for the incoming INVITE request in 793 * rdata with status code st_code and optional status text st_text. Use 794 * #pjsip_inv_answer() to create subsequent response message. 795 */ 796 PJ_DECL(pj_status_t) pjsip_inv_initial_answer( pjsip_inv_session *inv, 797 pjsip_rx_data *rdata, 798 int st_code, 799 const pj_str_t *st_text, 800 const pjmedia_sdp_session *sdp, 801 pjsip_tx_data **p_tdata); 802 803 /** 804 * Create a response message to an INVITE request. 805 * 806 * @param inv The UAS invite session. 807 * @param st_code The st_code contains the status code to be sent, 808 * which may be a provisional or final response. 809 * @param st_text If custom status text is desired, application can 810 * specify the text in st_text; otherwise if this 811 * argument is NULL, default status text will be used. 812 * @param local_sdp If application has specified its media capability 813 * during creation of UAS invite session, the local_sdp 814 * argument MUST be NULL. This is because application 815 * can not perform more than one SDP offer/answer session 816 * in a single INVITE transaction. 817 * If application has not specified its media capability 818 * during creation of UAS invite session, it MAY or MUST 819 * specify its capability in local_sdp argument, 820 * depending whether st_code indicates a 2xx final 821 * response. 822 * @param p_tdata Pointer to receive the response message created by 823 * this function. 824 * 825 * @return PJ_SUCCESS if response message was created 826 * successfully. 827 */ 828 PJ_DECL(pj_status_t) pjsip_inv_answer( pjsip_inv_session *inv, 829 int st_code, 830 const pj_str_t *st_text, 831 const pjmedia_sdp_session *local_sdp, 832 pjsip_tx_data **p_tdata ); 833 834 835 /** 836 * Set local offer or answer depending on negotiator state (it may also 837 * create a negotiator if it doesn't exist yet). 838 * 839 * @param inv The invite session. 840 * @param sdp The SDP description which will be set as 841 * an offer/answer to remote. 842 * 843 * @return PJ_SUCCESS if local offer/answer can be accepted by 844 * SDP negotiator. 845 */ 846 PJ_DECL(pj_status_t) pjsip_inv_set_local_sdp(pjsip_inv_session *inv, 847 const pjmedia_sdp_session *sdp ); 848 849 850 /** 851 * Set local answer to respond to remote SDP offer, to be carried by 852 * subsequent response (or request). 853 * 854 * @param inv The invite session. 855 * @param sdp The SDP description which will be set as answer 856 * to remote. 857 * 858 * @return PJ_SUCCESS if local answer can be accepted by 859 * SDP negotiator. 860 */ 861 PJ_DECL(pj_status_t) pjsip_inv_set_sdp_answer(pjsip_inv_session *inv, 862 const pjmedia_sdp_session *sdp ); 863 864 865 /** 866 * Create a SIP message to initiate invite session termination. Depending on 867 * the state of the session, this function may return CANCEL request, 868 * a non-2xx final response, a BYE request, or even no request. 869 * 870 * For UAS, if the session has not answered the incoming INVITE, this function 871 * creates the non-2xx final response with the specified status code in 872 * \a st_code and optional status text in \a st_text. 873 * 874 * For UAC, if the original INVITE has not been answered with a final 875 * response, the behavior depends on whether provisional response has been 876 * received. If provisional response has been received, this function will 877 * create CANCEL request. If no provisional response has been received, the 878 * function will not create CANCEL request (the function will return 879 * PJ_SUCCESS but the \a p_tdata will contain NULL) because we cannot send 880 * CANCEL before receiving provisional response. If then a provisional 881 * response is received, the invite session will send CANCEL automatically. 882 * 883 * For both UAC and UAS, if the INVITE session has been answered with final 884 * response, a BYE request will be created. 885 * 886 * @param inv The invite session. 887 * @param st_code Status code to be used for terminating the session. 888 * @param st_text Optional status text. 889 * @param p_tdata Pointer to receive the message to be created. Note 890 * that it's possible to receive NULL here while the 891 * function returns PJ_SUCCESS, see the description. 892 * 893 * @return PJ_SUCCESS if termination is initiated. 894 */ 895 PJ_DECL(pj_status_t) pjsip_inv_end_session( pjsip_inv_session *inv, 896 int st_code, 897 const pj_str_t *st_text, 898 pjsip_tx_data **p_tdata ); 899 900 901 /** 902 * Create a CANCEL request for an ongoing re-INVITE transaction. If no 903 * provisional response has been received, the function will not create 904 * CANCEL request (the function will return PJ_SUCCESS but the \a p_tdata 905 * will contain NULL) because we cannot send CANCEL before receiving 906 * provisional response. If then a provisional response is received, 907 * the invite session will send CANCEL automatically. 908 * 909 * @param inv The invite session. 910 * @param p_tdata Pointer to receive the message to be created. Note 911 * that it's possible to receive NULL here while the 912 * function returns PJ_SUCCESS, see the description. 913 * 914 * @return PJ_SUCCESS if termination is initiated. 915 */ 916 PJ_DECL(pj_status_t) pjsip_inv_cancel_reinvite( pjsip_inv_session *inv, 917 pjsip_tx_data **p_tdata ); 918 919 920 /** 921 * Create a re-INVITE request. 922 * 923 * @param inv The invite session. 924 * @param new_contact If application wants to update its local contact and 925 * inform peer to perform target refresh with a new 926 * contact, it can specify the new contact in this 927 * argument; otherwise this argument must be NULL. 928 * @param new_offer Application MAY initiate a new SDP offer/answer 929 * session in the request when there is no pending 930 * answer to be sent or received. It can detect this 931 * condition by observing the state of the SDP 932 * negotiator of the invite session. If new offer 933 * should be sent to remote, the offer must be specified 934 * in this argument, otherwise it must be NULL. 935 * @param p_tdata Pointer to receive the re-INVITE request message to 936 * be created. 937 * 938 * @return PJ_SUCCESS if a re-INVITE request with the specified 939 * characteristics (e.g. to contain new offer) can be 940 * created. 941 */ 942 PJ_DECL(pj_status_t) pjsip_inv_reinvite(pjsip_inv_session *inv, 943 const pj_str_t *new_contact, 944 const pjmedia_sdp_session *new_offer, 945 pjsip_tx_data **p_tdata ); 946 947 948 949 /** 950 * Create an UPDATE request to initiate new SDP offer. 951 * 952 * @param inv The invite session. 953 * @param new_contact If application wants to update its local contact 954 * and inform peer to perform target refresh with a new 955 * contact, it can specify the new contact in this 956 * argument; otherwise this argument must be NULL. 957 * @param offer Offer to be sent to remote. This argument is 958 * mandatory. 959 * @param p_tdata Pointer to receive the UPDATE request message to 960 * be created. 961 * 962 * @return PJ_SUCCESS if a UPDATE request with the specified 963 * characteristics (e.g. to contain new offer) can be 964 * created. 965 */ 966 PJ_DECL(pj_status_t) pjsip_inv_update ( pjsip_inv_session *inv, 967 const pj_str_t *new_contact, 968 const pjmedia_sdp_session *offer, 969 pjsip_tx_data **p_tdata ); 970 971 972 /** 973 * Create an ACK request. Normally ACK request transmission is handled 974 * by the framework. Application only needs to use this function if it 975 * handles the ACK transmission manually, by overriding \a on_send_ack() 976 * callback in #pjsip_inv_callback. 977 * 978 * Note that if the invite session has a pending offer to be answered 979 * (for example when the last 2xx response to INVITE contains an offer), 980 * application MUST have set the SDP answer with #pjsip_inv_set_sdp_answer() 981 * prior to creating the ACK request. In this case, the ACK request 982 * will be added with SDP message body. 983 * 984 * @param inv The invite session. 985 * @param cseq Mandatory argument to specify the CSeq of the 986 * ACK request. This value MUST match the value 987 * of the INVITE transaction to be acknowledged. 988 * @param p_tdata Pointer to receive the ACK request message to 989 * be created. 990 * 991 * @return PJ_SUCCESS if ACK request has been created. 992 */ 993 PJ_DECL(pj_status_t) pjsip_inv_create_ack(pjsip_inv_session *inv, 994 int cseq, 995 pjsip_tx_data **p_tdata); 996 997 998 /** 999 * Send request or response message in tdata. 1000 * 1001 * @param inv The invite session. 1002 * @param tdata The message to be sent. 1003 * 1004 * @return PJ_SUCCESS if transaction can be initiated 1005 * successfully to send this message. Note that the 1006 * actual final state of the transaction itself will 1007 * be reported later, in on_tsx_state_changed() 1008 * callback. 1009 */ 1010 PJ_DECL(pj_status_t) pjsip_inv_send_msg(pjsip_inv_session *inv, 1011 pjsip_tx_data *tdata); 1012 1013 1014 /** 1015 * Get the invite session for the dialog, if any. 1016 * 1017 * @param dlg The dialog which invite session is being queried. 1018 * 1019 * @return The invite session instance which has been 1020 * associated with this dialog, or NULL. 1021 */ 1022 PJ_DECL(pjsip_inv_session*) pjsip_dlg_get_inv_session(pjsip_dialog *dlg); 1023 1024 /** 1025 * Get the invite session instance associated with transaction tsx, if any. 1026 * 1027 * @param tsx The transaction, which invite session is being 1028 * queried. 1029 * 1030 * @return The invite session instance which has been 1031 * associated with this transaction, or NULL. 1032 */ 1033 PJ_DECL(pjsip_inv_session*) pjsip_tsx_get_inv_session(pjsip_transaction *tsx); 1034 1035 1036 /** 1037 * Get state names for INVITE session state. 1038 * 1039 * @param state The invite state. 1040 * 1041 * @return String describing the state. 1042 */ 1043 PJ_DECL(const char *) pjsip_inv_state_name(pjsip_inv_state state); 1044 1045 1046 /** 1047 * This is a utility function to create SIP body for SDP content. 1048 * 1049 * @param pool Pool to allocate memory. 1050 * @param sdp SDP session to be put in the SIP message body. 1051 * @param p_body Pointer to receive SIP message body containing 1052 * the SDP session. 1053 * 1054 * @return PJ_SUCCESS on success. 1055 */ 1056 PJ_DECL(pj_status_t) pjsip_create_sdp_body(pj_pool_t *pool, 1057 pjmedia_sdp_session *sdp, 1058 pjsip_msg_body **p_body); 1059 1060 /** 1061 * Retrieve SDP information from an incoming message. Application should 1062 * prefer to use this function rather than parsing the SDP manually since 1063 * this function supports multipart message body. 1064 * 1065 * This function will only parse the SDP once, the first time it is called 1066 * on the same message. Subsequent call on the same message will just pick 1067 * up the already parsed SDP from the message. 1068 * 1069 * @param rdata The incoming message. 1070 * 1071 * @return The SDP info. 1072 */ 1073 PJ_DECL(pjsip_rdata_sdp_info*) pjsip_rdata_get_sdp_info(pjsip_rx_data *rdata); 1074 1075 1076 /** 1077 * Retrieve SDP information from an incoming message. Application should 1078 * prefer to use this function rather than parsing the SDP manually since 1079 * this function supports multipart message body. 1080 * 1081 * This function will only parse the SDP once, the first time it is called 1082 * on the same message. Subsequent call on the same message will just pick 1083 * up the already parsed SDP from the message. 1084 * 1085 * @param rdata The incoming message. 1086 * @param med_type The SDP media type. 1087 * 1088 * @return The SDP info. 1089 */ 1090 PJ_DECL(pjsip_rdata_sdp_info*) pjsip_rdata_get_sdp_info2( 1091 pjsip_rx_data *rdata, 1092 const pjsip_media_type *med_type); 1093 1094 1095 PJ_END_DECL 1096 1097 /** 1098 * @} 1099 */ 1100 1101 1102 #endif /* __SIP_INVITE_SESSION_H__ */ 1103