@voipsdk/react-native-voipcloud 1.0.1 → 1.0.2

package/ios/VoipCloud.xcframework/ios-arm64/Headers/pjsip-ua/sip_inv.h

@@ -0,0 +1,1224 @@
+/* 
+ * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
+ * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
+ */
+#ifndef __SIP_INVITE_SESSION_H__
+#define __SIP_INVITE_SESSION_H__
+
+/**
+ * @file sip_inv.h
+ * @brief INVITE sessions
+ */
+
+
+#include <pjsip/sip_dialog.h>
+#include <pjmedia/sdp_neg.h>
+
+
+/**
+ * @defgroup PJSIP_HIGH_UA User Agent Library
+ * @brief Mid-level User Agent Library.
+ *
+ * This is the high level user agent library, which consists of:
+ *  - @ref PJSIP_INV, to encapsulate INVITE sessions and SDP
+ *    negotiation in the session,
+ *  - @ref PJSUA_REGC, high level client registration API, and
+ *  - @ref PJSUA_XFER.
+ *
+ * More detailed information is explained in
+ * <A HREF="/docs.htm">PJSIP Developer's Guide</A>
+ * PDF document, and readers are encouraged to read the document to
+ * get the concept behind dialog, dialog usages, and INVITE sessions.
+ *
+ * The User Agent Library is implemented in <b>pjsip-ua</b> static
+ * library.
+ */
+
+/**
+ * @defgroup PJSIP_INV INVITE Session
+ * @ingroup PJSIP_HIGH_UA
+ * @brief Provides INVITE session management.
+ * @{
+ *
+ * The INVITE session uses the @ref PJSIP_DIALOG framework to manage
+ * the underlying dialog, and is one type of usages that can use
+ * a particular dialog instance (other usages are event subscription,
+ * discussed in @ref PJSIP_EVENT_NOT). The INVITE session manages
+ * the life-time of the session, and also manages the SDP negotiation.
+ *
+ * Application must link with  <b>pjsip-ua</b> static library to use this API.
+ *
+ * More detailed information is explained in
+ * <A HREF="/docs.htm">PJSIP Developer's Guide</A>
+ * PDF document, and readers are encouraged to read the document to
+ * get the concept behind dialog, dialog usages, and INVITE sessions.
+ *
+ * The INVITE session does NOT manage media. If application wants to
+ * use API that encapsulates both signaling and media in a very easy
+ * to use API, it can use @ref PJSUA_LIB for this purpose.
+ */
+
+PJ_BEGIN_DECL
+
+
+/**
+ * @see pjsip_inv_session
+ */
+typedef struct pjsip_inv_session pjsip_inv_session;
+
+
+/**
+ * This enumeration describes invite session state.
+ */
+typedef enum pjsip_inv_state
+{
+    PJSIP_INV_STATE_NULL,           /**< Before INVITE is sent or received  */
+    PJSIP_INV_STATE_CALLING,        /**< After INVITE is sent               */
+    PJSIP_INV_STATE_INCOMING,       /**< After INVITE is received.          */
+    PJSIP_INV_STATE_EARLY,          /**< After response with To tag.        */
+    PJSIP_INV_STATE_CONNECTING,     /**< After 2xx is sent/received.        */
+    PJSIP_INV_STATE_CONFIRMED,      /**< After ACK is sent/received.        */
+    PJSIP_INV_STATE_DISCONNECTED,   /**< Session is terminated.             */
+} pjsip_inv_state;
+
+/**
+ * Structure to hold parameters when calling the callback
+ * on_rx_offer2().
+ */
+struct pjsip_inv_on_rx_offer_cb_param
+{
+    const pjmedia_sdp_session   *offer;     /**< Remote offer.              */
+    const pjsip_rx_data         *rdata;     /**< The received request.      */
+};
+
+
+/**
+ * This structure contains callbacks to be registered by application to 
+ * receive notifications from the framework about various events in
+ * the invite session.
+ */
+typedef struct pjsip_inv_callback
+{
+    /**
+     * This callback is called when the invite sesion state has changed. 
+     * Application should inspect the session state (inv_sess->state) to get 
+     * the current state of the session.
+     *
+     * This callback is mandatory.
+     *
+     * @param inv       The invite session.
+     * @param e         The event which has caused the invite session's 
+     *                  state to change.
+     */
+    void (*on_state_changed)(pjsip_inv_session *inv, pjsip_event *e);
+
+    /**
+     * This callback is called when the invite usage module has created 
+     * a new dialog and invite because of forked outgoing request.
+     *
+     * Currently the invite session does not create a new dialog in
+     * forking scenario, so this callback will never be invoked.
+     *
+     * @param inv       The new invite session.
+     * @param e         The event which has caused the dialog to fork.
+     *                  The type of this event can be either
+     *                  PJSIP_EVENT_RX_MSG or PJSIP_EVENT_RX_200_MSG.
+     */
+    void (*on_new_session)(pjsip_inv_session *inv, pjsip_event *e);
+
+    /**
+     * This callback is called whenever any transactions within the session
+     * has changed their state. Application MAY implement this callback, 
+     * e.g. to monitor the progress of an outgoing request, or to send
+     * response to unhandled incoming request (such as INFO).
+     *
+     * This callback is optional.
+     *
+     * @param inv       The invite session.
+     * @param tsx       The transaction, which state has changed.
+     * @param e         The event which has caused the transation state's
+     *                  to change.
+     */
+    void (*on_tsx_state_changed)(pjsip_inv_session *inv,
+                                 pjsip_transaction *tsx,
+                                 pjsip_event *e);
+
+    /**
+     * This callback is called when the invite session has received 
+     * new offer from peer. Application can inspect the remote offer 
+     * in "offer", and set the SDP answer with #pjsip_inv_set_sdp_answer().
+     * When the application sends a SIP message to send the answer, 
+     * this SDP answer will be negotiated with the offer, and the result
+     * will be sent with the SIP message.
+     *
+     * Note: if callback #on_rx_offer2() is implemented, this callback will
+     * not be called.
+     *
+     * @param inv       The invite session.
+     * @param offer     Remote offer.
+     */
+    void (*on_rx_offer)(pjsip_inv_session *inv,
+                        const pjmedia_sdp_session *offer);
+
+    /**
+     * This callback is called when the invite session has received 
+     * new offer from peer. Variant of #on_rx_offer() callback.
+     *
+     * @param inv       The invite session.
+     * @param param     The callback parameters.
+     */
+    void (*on_rx_offer2)(pjsip_inv_session *inv,
+                         struct pjsip_inv_on_rx_offer_cb_param *param);
+
+    /**
+     * This callback is optional, and is called when the invite session has
+     * received a re-INVITE from the peer. It will be called after
+     * on_rx_offer() callback and works only for re-INVITEs. It allows more
+     * fine-grained control over the response to a re-INVITE, e.g. sending
+     * a provisional response first. Application can return PJ_SUCCESS and
+     * send a reply using the function #pjsip_inv_initial_answer() or
+     * #pjsip_inv_answer(), as with the initial INVITE. If application
+     * returns non-PJ_SUCCESS, it needs to set the SDP answer with
+     * #pjsip_inv_set_sdp_answer() and the re-INVITE will be answered
+     * automatically.
+     *
+     * Remarks: Application may need to monitor on_tsx_state_changed()
+     * callback to check whether the re-INVITE is already answered
+     * automatically with 487 due to being cancelled.
+     *
+     * @param inv       The invite session.
+     * @param offer     Remote offer.
+     * @param rdata     The received re-INVITE request.
+     *
+     * @return          - PJ_SUCCESS: application will answer the re-INVITE
+     *                    manually
+     *                  - non-PJ_SUCCESS: answer the re-INVITE automatically
+     *                    using the SDP set via #pjsip_inv_set_sdp_answer()
+     */
+    pj_status_t (*on_rx_reinvite)(pjsip_inv_session *inv,
+                                  const pjmedia_sdp_session *offer,
+                                  pjsip_rx_data *rdata);
+
+    /**
+     * This callback is optional, and it is used to ask the application
+     * to create a fresh offer, when the invite session has received 
+     * re-INVITE without offer. This offer then will be sent in the
+     * 200/OK response to the re-INVITE request.
+     *
+     * If application doesn't implement this callback, the invite session
+     * will send the currently active SDP as the offer.
+     *
+     * @param inv       The invite session.
+     * @param p_offer   Pointer to receive the SDP offer created by
+     *                  application.
+     */
+    void (*on_create_offer)(pjsip_inv_session *inv,
+                            pjmedia_sdp_session **p_offer);
+
+    /**
+     * This callback is called after SDP offer/answer session has completed.
+     * The status argument specifies the status of the offer/answer, 
+     * i.e. whether the SDP answer is valid or the negotiation result
+     * as returned by pjmedia_sdp_neg_negotiate().
+     * 
+     * This callback is optional (from the point of view of the framework), 
+     * but all useful applications normally need to implement this callback.
+     *
+     * @param inv       The invite session.
+     * @param status    The negotiation status.
+     */
+    void (*on_media_update)(pjsip_inv_session *inv_ses, 
+                            pj_status_t status);
+
+    /**
+     * This callback is called when the framework needs to send
+     * ACK request after it receives incoming  2xx response for 
+     * INVITE. It allows application to manually handle the 
+     * transmission of ACK request, which is required by some 3PCC
+     * scenarios. If this callback is not implemented, the framework
+     * will handle the ACK transmission automatically.
+     *
+     * When this callback is overridden, application may delay the
+     * sending of the ACK request (for example, when it needs to 
+     * wait for answer from the other call leg, in 3PCC scenarios). 
+     *
+     * Application MUST create the ACK request using pjsip_inv_create_ack()
+     * and send it using pjsip_inv_send_msg().
+     *
+     * Once it has sent the ACK request, the framework will keep 
+     * this ACK request in the cache. Subsequent receipt of 2xx response
+     * will not cause this callback to be called (but see exception below),
+     * and instead automatic retransmission of this ACK request from
+     * the cache will be done by the framework.
+     * Exception: if app has created the ACK but has not sent it,
+     * while it receives a retransmission of 2xx response, this callback
+     * will be called again.
+     *
+     * This callback is optional.
+     */
+    void (*on_send_ack)(pjsip_inv_session *inv, pjsip_rx_data *rdata);
+
+    /**
+     * This callback is called when the session is about to resend the 
+     * INVITE request to the specified target, following the previously
+     * received redirection response.
+     *
+     * Application may accept the redirection to the specified target 
+     * (the default behavior if this callback is implemented), reject 
+     * this target only and make the session continue to try the next 
+     * target in the list if such target exists, stop the whole
+     * redirection process altogether and cause the session to be
+     * disconnected, or defer the decision to ask for user confirmation.
+     *
+     * This callback is optional. If this callback is not implemented,
+     * the default behavior is to NOT follow the redirection response.
+     *
+     * @param inv       The invite session.
+     * @param target    The current target to be tried.
+     * @param e         The event that caused this callback to be called.
+     *                  This could be the receipt of 3xx response, or
+     *                  4xx/5xx response received for the INVITE sent to
+     *                  subsequent targets, or NULL if this callback is
+     *                  called from within #pjsip_inv_process_redirect()
+     *                  context.
+     *
+     * @return          Action to be performed for the target. Set this
+     *                  parameter to one of the value below:
+     *                  - PJSIP_REDIRECT_ACCEPT: immediately accept the
+     *                    redirection to this target. When set, the
+     *                    session will immediately resend INVITE request
+     *                    to the target after this callback returns.
+     *                  - PJSIP_REDIRECT_REJECT: immediately reject this
+     *                    target. The session will continue retrying with
+     *                    next target if present, or disconnect the call
+     *                    if there is no more target to try.
+     *                  - PJSIP_REDIRECT_STOP: stop the whole redirection
+     *                    process and immediately disconnect the call. The
+     *                    on_state_changed() callback will be called with
+     *                    PJSIP_INV_STATE_DISCONNECTED state immediately
+     *                    after this callback returns.
+     *                  - PJSIP_REDIRECT_PENDING: set to this value if
+     *                    no decision can be made immediately (for example
+     *                    to request confirmation from user). Application
+     *                    then MUST call #pjsip_inv_process_redirect()
+     *                    to either accept or reject the redirection upon
+     *                    getting user decision.
+     */
+    pjsip_redirect_op (*on_redirected)(pjsip_inv_session *inv, 
+                                       const pjsip_uri *target,
+                                       const pjsip_event *e);
+
+} pjsip_inv_callback;
+
+
+
+/**
+ * This enumeration shows various options that can be applied to a session. 
+ * The bitmask combination of these options need to be specified when 
+ * creating a session. After the dialog is established (including early), 
+ * the options member of #pjsip_inv_session shows which capabilities are 
+ * common in both endpoints.
+ */
+enum pjsip_inv_option
+{       
+    /** 
+     * Indicate support for reliable provisional response extension 
+     */
+    PJSIP_INV_SUPPORT_100REL    = 1,
+
+    /** 
+     * Indicate support for session timer extension. 
+     */
+    PJSIP_INV_SUPPORT_TIMER     = 2,
+
+    /** 
+     * Indicate support for UPDATE method. This is automatically implied
+     * when creating outgoing dialog. After the dialog is established,
+     * the options member of #pjsip_inv_session shows whether peer supports
+     * this method as well.
+     */
+    PJSIP_INV_SUPPORT_UPDATE    = 4,
+
+    /**
+     * Indicate support for ICE
+     */
+    PJSIP_INV_SUPPORT_ICE       = 8,
+
+    /**
+     * Require ICE support.
+     */
+    PJSIP_INV_REQUIRE_ICE       = 16,
+
+    /** 
+     * Require reliable provisional response extension. 
+     */
+    PJSIP_INV_REQUIRE_100REL    = 32,
+
+    /**  
+     * Require session timer extension. 
+     */
+    PJSIP_INV_REQUIRE_TIMER     = 64,
+
+    /**  
+     * Session timer extension will always be used even when peer doesn't
+     * support/want session timer.
+     */
+    PJSIP_INV_ALWAYS_USE_TIMER  = 128,
+
+    /**
+     * Indicate support for trickle ICE
+     */
+    PJSIP_INV_SUPPORT_TRICKLE_ICE = 256,
+
+    /**
+     * Require trickle ICE support.
+     */
+    PJSIP_INV_REQUIRE_TRICKLE_ICE = 512,
+
+};
+
+/* Forward declaration of Session Timers */
+struct pjsip_timer;
+
+/**
+ * This structure describes the invite session.
+ *
+ * Note regarding the invite session's pools. The inv_sess used to have
+ * only one pool, which is just a pointer to the dialog's pool. Ticket
+ * https://github.com/pjsip/pjproject/issues/877 has found that the memory
+ * usage will grow considerably everytime re-INVITE or UPDATE is
+ * performed.
+ *
+ * Ticket #877 then created two more memory pools for the inv_sess, so
+ * now we have three memory pools:
+ *  - pool: to be used to allocate long term data for the session
+ *  - pool_prov and pool_active: this is a flip-flop pools to be used
+ *     interchangably during re-INVITE and UPDATE. pool_prov is
+ *     "provisional" pool, used to allocate SDP offer or answer for
+ *     the re-INVITE and UPDATE. Once SDP negotiation is done, the
+ *     provisional pool will be made as the active pool, then the
+ *     existing active pool will be reset, to release the memory
+ *     back to the OS. So these pool's lifetime is synchronized to
+ *     the SDP offer-answer negotiation.
+ *
+ * Higher level application such as PJSUA-LIB has been modified to
+ * make use of these flip-flop pools, i.e. by creating media objects
+ * from the provisional pool rather than from the long term pool.
+ *
+ * Other applications that want to use these pools must understand
+ * that the flip-flop pool's lifetimes are synchronized to the
+ * SDP offer-answer negotiation.
+ *
+ * The lifetime of this session is controlled by the reference counter in this
+ * structure, which is manipulated by calling #pjsip_inv_add_ref and
+ * #pjsip_inv_dec_ref. When the reference counter has reached zero, then
+ * this session will be destroyed.
+ */
+struct pjsip_inv_session
+{
+    char                 obj_name[PJ_MAX_OBJ_NAME]; /**< Log identification */
+    pj_pool_t           *pool;                      /**< Long term pool.    */
+    pj_pool_t           *pool_prov;                 /**< Provisional pool   */
+    pj_pool_t           *pool_active;               /**< Active/current pool*/
+    pjsip_inv_state      state;                     /**< Invite sess state. */
+    pj_bool_t            cancelling;                /**< CANCEL requested   */
+    pj_bool_t            pending_cancel;            /**< Wait to send CANCEL*/
+    pjsip_tx_data       *pending_bye;               /**< BYE to send later  */
+    pjsip_status_code    cause;                     /**< Disconnect cause.  */
+    pj_str_t             cause_text;                /**< Cause text.        */
+    pj_bool_t            notify;                    /**< Internal.          */
+    pj_bool_t            sdp_done_early_rel;        /**< Nego done in early
+                                                         med was reliable?  */
+    unsigned             cb_called;                 /**< Cb has been called */
+    pjsip_dialog        *dlg;                       /**< Underlying dialog. */
+    pjsip_role_e         role;                      /**< Invite role.       */
+    unsigned             options;                   /**< Options in use.    */
+    pjmedia_sdp_neg     *neg;                       /**< Negotiator.        */
+    unsigned             sdp_neg_flags;             /**< SDP neg flags.     */
+    pjsip_transaction   *invite_tsx;                /**< 1st invite tsx.    */
+    pjsip_tx_data       *invite_req;                /**< Saved invite req   */
+    pjsip_tx_data       *last_answer;               /**< Last INVITE resp.  */
+    pjsip_tx_data       *last_ack;                  /**< Last ACK request   */
+    pj_int32_t           last_ack_cseq;             /**< CSeq of last ACK   */
+    void                *mod_data[PJSIP_MAX_MODULE];/**< Modules data.      */
+    struct pjsip_timer  *timer;                     /**< Session Timers.    */
+    pj_bool_t            following_fork;            /**< Internal, following
+                                                         forked media?      */
+    pj_atomic_t         *ref_cnt;                   /**< Reference counter. */
+    pj_bool_t            updated_sdp_answer;        /**< SDP answer just been
+                                                         updated?           */
+};
+
+
+/**
+ * This structure represents SDP information in a pjsip_(rx|tx)_data. Application
+ * retrieve this information by calling #pjsip_get_sdp_info(). This
+ * mechanism supports multipart message body.
+ */
+typedef struct pjsip_sdp_info
+{
+    /**
+     * Pointer and length of the text body in the incoming message. If
+     * the pointer is NULL, it means the message does not contain SDP
+     * body.
+     */
+    pj_str_t             body;
+
+    /**
+     * This will contain non-zero if an invalid SDP body is found in the
+     * message.
+     */
+    pj_status_t          sdp_err;
+
+    /**
+     * A parsed and validated SDP body.
+     */
+    pjmedia_sdp_session *sdp;
+
+} pjsip_sdp_info;
+
+/**
+ * For backwards compatibility and completeness,
+ * pjsip_rdata_sdp_info and pjsip_tdata_sdp_info
+ * are typedef'd to pjsip_sdp_info.
+ */
+typedef pjsip_sdp_info pjsip_rdata_sdp_info;
+
+/**
+ * For backwards compatibility and completeness,
+ * pjsip_rdata_sdp_info and pjsip_tdata_sdp_info
+ * are typedef'd to pjsip_sdp_info.
+ */
+typedef pjsip_sdp_info pjsip_tdata_sdp_info;
+
+
+/**
+ * Initialize the invite usage module and register it to the endpoint. 
+ * The callback argument contains pointer to functions to be called on 
+ * occurences of events in invite sessions.
+ *
+ * @param endpt         The endpoint instance.
+ * @param cb            Callback structure.
+ *
+ * @return              PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_usage_init(pjsip_endpoint *endpt,
+                                          const pjsip_inv_callback *cb);
+
+/**
+ * Get the INVITE usage module instance.
+ *
+ * @return              PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pjsip_module*) pjsip_inv_usage_instance(void);
+
+
+/**
+ * Dump user agent contents (e.g. all dialogs).
+ */
+PJ_DECL(void) pjsip_inv_usage_dump(void);
+
+
+/**
+ * Create UAC invite session for the specified dialog in dlg. 
+ *
+ * @param dlg           The dialog which will be used by this invite session.
+ * @param local_sdp     If application has determined its media capability, 
+ *                      it can specify the SDP here. Otherwise it can leave 
+ *                      this to NULL, if app wishes to specify the SDP at
+ *                      a later time using the API pjsip_inv_set_local_sdp(),
+ *                      or if it wants to let remote UAS specify an offer.
+ * @param options       The options argument is bitmask combination of SIP 
+ *                      features in pjsip_inv_option enumeration.
+ * @param p_inv         On successful return, the invite session will be put 
+ *                      in this argument.
+ *
+ * @return              The function will return PJ_SUCCESS if it can create
+ *                      the session. Otherwise the appropriate error status 
+ *                      will be returned on failure.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_create_uac(pjsip_dialog *dlg,
+                                          const pjmedia_sdp_session *local_sdp,
+                                          unsigned options,
+                                          pjsip_inv_session **p_inv);
+
+
+/**
+ * Application SHOULD call this function upon receiving the initial INVITE 
+ * request in rdata before creating the invite session (or even dialog), 
+ * to verify that the invite session can handle the INVITE request. 
+ * This function verifies that local endpoint is capable to handle required 
+ * SIP extensions in the request (i.e. Require header) and also the media, 
+ * if media description is present in the request.
+ *
+ * @param rdata         The incoming INVITE request.
+ *
+ * @param options       Upon calling this function, the options argument 
+ *                      MUST contain the desired SIP extensions to be 
+ *                      applied to the session. Upon return, this argument 
+ *                      will contain the SIP extension that will be applied 
+ *                      to the session, after considering the Supported, 
+ *                      Require, and Allow headers in the request.
+ *
+ * @param sdp           If local media capability has been determined, 
+ *                      and if application wishes to verify that it can 
+ *                      handle the media offer in the incoming INVITE 
+ *                      request, it SHOULD specify its local media capability
+ *                      in this argument. 
+ *                      If it is not specified, media verification will not
+ *                      be performed by this function.
+ *
+ * @param dlg           If tdata is not NULL, application needs to specify
+ *                      how to create the response. Either dlg or endpt
+ *                      argument MUST be specified, with dlg argument takes
+ *                      precedence when both are specified.
+ *
+ *                      If a dialog has been created prior to calling this 
+ *                      function, then it MUST be specified in dlg argument. 
+ *                      Otherwise application MUST specify the endpt argument
+ *                      (this is useful e.g. when application wants to send 
+ *                      the response statelessly).
+ *
+ * @param endpt         If tdata is not NULL, application needs to specify
+ *                      how to create the response. Either dlg or endpt
+ *                      argument MUST be specified, with dlg argument takes
+ *                      precedence when both are specified.
+ *
+ * @param tdata         If this argument is not NULL, this function will 
+ *                      create the appropriate non-2xx final response message
+ *                      when the verification fails.
+ *
+ * @return              If everything has been negotiated successfully, 
+ *                      the function will return PJ_SUCCESS. Otherwise it 
+ *                      will return the reason of the failure as the return
+ *                      code.
+ *
+ *                      This function is capable to create the appropriate 
+ *                      response message when the verification has failed. 
+ *                      If tdata is specified, then a non-2xx final response
+ *                      will be created and put in this argument upon return,
+ *                      when the verification has failed. 
+ *
+ *                      If a dialog has been created prior to calling this 
+ *                      function, then it MUST be specified in dlg argument. 
+ *                      Otherwise application MUST specify the endpt argument
+ *                      (this is useful e.g. when application wants to send 
+ *                      the response statelessly).
+ *
+ * @see pjsip_inv_verify_request2()
+ */
+PJ_DECL(pj_status_t) pjsip_inv_verify_request(  pjsip_rx_data *rdata,
+                                                unsigned *options,
+                                                const pjmedia_sdp_session *sdp,
+                                                pjsip_dialog *dlg,
+                                                pjsip_endpoint *endpt,
+                                                pjsip_tx_data **tdata);
+
+/**
+ * Variant of #pjsip_inv_verify_request() which allows application to specify
+ * the parsed SDP in the \a offer argument. This is useful to avoid having to
+ * re-parse the SDP in the incoming request.
+ *
+ * @see pjsip_inv_verify_request()
+ */
+PJ_DECL(pj_status_t) pjsip_inv_verify_request2( pjsip_rx_data *rdata,
+                                                unsigned *options,
+                                                const pjmedia_sdp_session *offer,
+                                                const pjmedia_sdp_session *answer,
+                                                pjsip_dialog *dlg,
+                                                pjsip_endpoint *endpt,
+                                                pjsip_tx_data **tdata);
+
+/**
+ * Variant of #pjsip_inv_verify_request() which allows application not to
+ * specify the rdata (i.e. pass NULL as the rdata parameter) and specify
+ * the parsed SDP in the \a offer argument and a temporary pool in the
+ * \a tmp_pool argument.
+ * This is useful if application no longer has access to the rdata.
+ *
+ * @see pjsip_inv_verify_request()
+ */
+PJ_DECL(pj_status_t) pjsip_inv_verify_request3( pjsip_rx_data *rdata,
+                                                pj_pool_t *tmp_pool,
+                                                unsigned *options,
+                                                const pjmedia_sdp_session *offer,
+                                                const pjmedia_sdp_session *answer,
+                                                pjsip_dialog *dlg,
+                                                pjsip_endpoint *endpt,
+                                                pjsip_tx_data **tdata);
+
+
+/**
+ * Create UAS invite session for the specified dialog in dlg. Application 
+ * SHOULD call the verification function before calling this function, 
+ * to ensure that it can create the session successfully.
+ *
+ * @param dlg           The dialog to be used.
+ * @param rdata         Application MUST specify the received INVITE request 
+ *                      in rdata. The invite session needs to inspect the 
+ *                      received request to see if the request contains 
+ *                      features that it supports.
+ * @param local_sdp     If application has determined its media capability, 
+ *                      it can specify this capability in this argument. 
+ *                      If SDP is received in the initial INVITE, the UAS 
+ *                      capability specified in this argument doesn't have to
+ *                      match the received offer; the SDP negotiator is able 
+ *                      to rearrange the media lines in the answer so that it
+ *                      matches the offer. 
+ * @param options       The options argument is bitmask combination of SIP 
+ *                      features in pjsip_inv_option enumeration.
+ * @param p_inv         Pointer to receive the newly created invite session.
+ *
+ * @return              On successful, the invite session will be put in 
+ *                      p_inv argument and the function will return PJ_SUCCESS.
+ *                      Otherwise the appropriate error status will be returned 
+ *                      on failure.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_create_uas(pjsip_dialog *dlg,
+                                          pjsip_rx_data *rdata,
+                                          const pjmedia_sdp_session *local_sdp,
+                                          unsigned options,
+                                          pjsip_inv_session **p_inv);
+
+
+/**
+ * Add reference counter to the INVITE session. The reference counter controls
+ * the life time of the session, ie. when the counter reaches zero, then it 
+ * will be destroyed.
+ *
+ * @param inv       The INVITE session.
+ * @return          PJ_SUCCESS if the INVITE session reference counter
+ *                  was increased.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_add_ref( pjsip_inv_session *inv );
+
+/**
+ * Decrement reference counter of the INVITE session.
+ * When the session is no longer used, it will be destroyed and
+ * caller is informed with PJ_EGONE return status.
+ *
+ * @param inv       The INVITE session.
+ * @return          PJ_SUCCESS if the INVITE session reference counter
+ *                  was decreased. A status PJ_EGONE will be returned to 
+ *                  inform that session is destroyed.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_dec_ref( pjsip_inv_session *inv );
+
+
+/**
+ * Forcefully terminate and destroy INVITE session, regardless of
+ * the state of the session. Note that this function should only be used
+ * when there is failure in the INVITE session creation. After the
+ * invite session has been created and initialized, normally application
+ * SHOULD use #pjsip_inv_end_session() to end the INVITE session instead.
+ *
+ * Note also that this function may terminate the underlying dialog, if
+ * there are no other sessions in the dialog.
+ *
+ * @param inv           The invite session.
+ * @param st_code       Status code for the reason of the termination.
+ * @param notify        If set to non-zero, then on_state_changed() 
+ *                      callback will be called.
+ *
+ * @return              PJ_SUCCESS if the INVITE session has been
+ *                      terminated.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_terminate( pjsip_inv_session *inv,
+                                          int st_code,
+                                          pj_bool_t notify );
+
+
+/**
+ * Restart UAC session and prepare the session for a new initial INVITE.
+ * This function can be called for example when the application wants to
+ * follow redirection response with a new call reusing this session so
+ * that the new call will have the same Call-ID and From headers. After
+ * the session is restarted, application may create and send a new INVITE
+ * request.
+ *
+ * @param inv           The invite session.
+ * @param new_offer     Should be set to PJ_TRUE since the application will
+ *                      restart the session.
+ *
+ * @return              PJ_SUCCESS on successful operation.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_uac_restart(pjsip_inv_session *inv,
+                                           pj_bool_t new_offer);
+
+
+/**
+ * Accept or reject redirection response. Application MUST call this function
+ * after it signaled PJSIP_REDIRECT_PENDING in the \a on_redirected() 
+ * callback, to notify the invite session whether to accept or reject the
+ * redirection to the current target. Application can use the combination of
+ * PJSIP_REDIRECT_PENDING command in \a on_redirected() callback and this
+ * function to ask for user permission before redirecting the call.
+ *
+ * Note that if the application chooses to reject or stop redirection (by 
+ * using PJSIP_REDIRECT_REJECT or PJSIP_REDIRECT_STOP respectively), the
+ * session disconnection callback will be called before this function returns.
+ * And if the application rejects the target, the \a on_redirected() callback
+ * may also be called before this function returns if there is another target
+ * to try.
+ *
+ * @param inv           The invite session.
+ * @param cmd           Redirection operation. The semantic of this argument
+ *                      is similar to the description in the \a on_redirected()
+ *                      callback, except that the PJSIP_REDIRECT_PENDING is
+ *                      not accepted here.
+ * @param e             Should be set to NULL.
+ *
+ * @return              PJ_SUCCESS on successful operation.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_process_redirect(pjsip_inv_session *inv,
+                                                pjsip_redirect_op cmd,
+                                                pjsip_event *e);
+
+
+/**
+ * Create the initial INVITE request for this session. This function can only 
+ * be called for UAC session. If local media capability is specified when 
+ * the invite session was created, then this function will put an SDP offer 
+ * in the outgoing INVITE request. Otherwise the outgoing request will not 
+ * contain SDP body.
+ *
+ * @param inv           The UAC invite session.
+ * @param p_tdata       The initial INVITE request will be put in this 
+ *                      argument if it can be created successfully.
+ *
+ * @return              PJ_SUCCESS if the INVITE request can be created.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_invite( pjsip_inv_session *inv,
+                                       pjsip_tx_data **p_tdata );
+
+
+/**
+ * Create the initial response message for the incoming INVITE request in
+ * rdata with status code st_code and optional status text st_text. Use
+ * #pjsip_inv_answer() to create subsequent response message.
+ * 
+ * When this function returning non-PJ_SUCCESS, it may be caused by an 
+ * unacceptable INVITE request. In such cases the function will generate
+ * an appropriate answer in p_tdata, 
+ * e.g: when session timer header Session-Expires is too low, 
+ *      the generated answer will include Min-SE header. 
+ * If the generated answer is not sent, it must be destroyed.
+ * i.e: using #pjsip_tx_data_dec_ref(), to avoid resource leak.
+ *
+ * @param inv           The UAS invite session.
+ * @param rdata         The incoming request message.
+ * @param st_code       The st_code contains the status code to be sent,
+ *                      which may be a provisional or final response.
+ * @param st_text       If custom status text is desired, application can
+ *                      specify the text in st_text; otherwise if this
+ *                      argument is NULL, default status text will be used.
+ * @param sdp           If application has specified its media capability
+ *                      during creation of UAS invite session, the sdp
+ *                      argument MUST be NULL. This is because application
+ *                      can not perform more than one SDP offer/answer session
+ *                      in a single INVITE transaction.
+ *                      If application has not specified its media capability
+ *                      during creation of UAS invite session, it MAY or MUST
+ *                      specify its capability in sdp argument,
+ *                      depending whether st_code indicates a 2xx final
+ *                      response.
+ * @param p_tdata       Pointer to receive the response message created by
+ *                      this function.
+ *
+ * @return              PJ_SUCCESS if response message was created
+ *                      successfully.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_initial_answer(  pjsip_inv_session *inv,
+                                                pjsip_rx_data *rdata,
+                                                int st_code,
+                                                const pj_str_t *st_text,
+                                                const pjmedia_sdp_session *sdp,
+                                                pjsip_tx_data **p_tdata);
+
+/**
+ * Create a response message to an INVITE request.
+ *
+ * @param inv           The UAS invite session.
+ * @param st_code       The st_code contains the status code to be sent, 
+ *                      which may be a provisional or final response. 
+ * @param st_text       If custom status text is desired, application can 
+ *                      specify the text in st_text; otherwise if this 
+ *                      argument is NULL, default status text will be used.
+ * @param local_sdp     If application has specified its media capability
+ *                      during creation of UAS invite session, the local_sdp
+ *                      argument MUST be NULL. This is because application 
+ *                      can not perform more than one SDP offer/answer session
+ *                      in a single INVITE transaction.
+ *                      If application has not specified its media capability 
+ *                      during creation of UAS invite session, it MAY or MUST
+ *                      specify its capability in local_sdp argument, 
+ *                      depending whether st_code indicates a 2xx final 
+ *                      response.
+ * @param p_tdata       Pointer to receive the response message created by
+ *                      this function.
+ *
+ * @return              PJ_SUCCESS if response message was created
+ *                      successfully.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_answer(  pjsip_inv_session *inv,
+                                        int st_code,
+                                        const pj_str_t *st_text,
+                                        const pjmedia_sdp_session *local_sdp,
+                                        pjsip_tx_data **p_tdata );
+
+
+/**
+ * Set local offer or answer depending on negotiator state (it may also
+ * create a negotiator if it doesn't exist yet).
+ *
+ * @param inv           The invite session.
+ * @param sdp           The SDP description which will be set as
+ *                      an offer/answer to remote.
+ *
+ * @return              PJ_SUCCESS if local offer/answer can be accepted by
+ *                      SDP negotiator.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_set_local_sdp(pjsip_inv_session *inv,
+                                             const pjmedia_sdp_session *sdp );
+
+
+/**
+ * Set local answer to respond to remote SDP offer, to be carried by 
+ * subsequent response (or request).
+ *
+ * @param inv           The invite session.
+ * @param sdp           The SDP description which will be set as answer
+ *                      to remote.
+ *
+ * @return              PJ_SUCCESS if local answer can be accepted by
+ *                      SDP negotiator.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_set_sdp_answer(pjsip_inv_session *inv,
+                                              const pjmedia_sdp_session *sdp );
+
+
+/**
+ * Create a SIP message to initiate invite session termination. Depending on 
+ * the state of the session, this function may return CANCEL request, 
+ * a non-2xx final response, a BYE request, or even no request. 
+ *
+ * For UAS, if the session has not answered the incoming INVITE, this function
+ * creates the non-2xx final response with the specified status code in 
+ * \a st_code and optional status text in \a st_text. 
+ *
+ * For UAC, if the original INVITE has not been answered with a final 
+ * response, the behavior depends on whether provisional response has been
+ * received. If provisional response has been received, this function will
+ * create CANCEL request. If no provisional response has been received, the
+ * function will not create CANCEL request (the function will return 
+ * PJ_SUCCESS but the \a p_tdata will contain NULL) because we cannot send
+ * CANCEL before receiving provisional response. If then a provisional
+ * response is received, the invite session will send CANCEL automatically.
+ * 
+ * For both UAC and UAS, if the INVITE session has been answered with final
+ * response, a BYE request will be created.
+ *
+ * @param inv           The invite session.
+ * @param st_code       Status code to be used for terminating the session.
+ * @param st_text       Optional status text.
+ * @param p_tdata       Pointer to receive the message to be created. Note
+ *                      that it's possible to receive NULL here while the
+ *                      function returns PJ_SUCCESS, see the description.
+ *
+ * @return              PJ_SUCCESS if termination is initiated.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_end_session( pjsip_inv_session *inv,
+                                            int st_code,
+                                            const pj_str_t *st_text,
+                                            pjsip_tx_data **p_tdata );
+
+
+/**
+ * Create a CANCEL request for an ongoing re-INVITE transaction. If no
+ * provisional response has been received, the function will not create
+ * CANCEL request (the function will return PJ_SUCCESS but the \a p_tdata
+ * will contain NULL) because we cannot send CANCEL before receiving
+ * provisional response. If then a provisional response is received,
+ * the invite session will send CANCEL automatically.
+ *
+ * @param inv           The invite session.
+ * @param p_tdata       Pointer to receive the message to be created. Note
+ *                      that it's possible to receive NULL here while the
+ *                      function returns PJ_SUCCESS, see the description.
+ *
+ * @return              PJ_SUCCESS if termination is initiated.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_cancel_reinvite( pjsip_inv_session *inv,
+                                                pjsip_tx_data **p_tdata );
+
+
+/**
+ * Create a re-INVITE request. 
+ *
+ * @param inv           The invite session.
+ * @param new_contact   If application wants to update its local contact and
+ *                      inform peer to perform target refresh with a new 
+ *                      contact, it can specify the new contact in this 
+ *                      argument; otherwise this argument must be NULL.
+ * @param new_offer     Application MAY initiate a new SDP offer/answer 
+ *                      session in the request when there is no pending 
+ *                      answer to be sent or received. It can detect this 
+ *                      condition by observing the state of the SDP 
+ *                      negotiator of the invite session. If new offer 
+ *                      should be sent to remote, the offer must be specified
+ *                      in this argument, otherwise it must be NULL.
+ * @param p_tdata       Pointer to receive the re-INVITE request message to
+ *                      be created.
+ *
+ * @return              PJ_SUCCESS if a re-INVITE request with the specified
+ *                      characteristics (e.g. to contain new offer) can be 
+ *                      created.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_reinvite(pjsip_inv_session *inv,
+                                        const pj_str_t *new_contact,
+                                        const pjmedia_sdp_session *new_offer,
+                                        pjsip_tx_data **p_tdata );
+
+
+
+/**
+ * Create an UPDATE request to initiate new SDP offer.
+ *
+ * @param inv           The invite session.
+ * @param new_contact   If application wants to update its local contact
+ *                      and inform peer to perform target refresh with a new
+ *                      contact, it can specify the new contact in this 
+ *                      argument; otherwise this argument must be NULL.
+ * @param offer         Offer to be sent to remote. This argument is
+ *                      mandatory.
+ * @param p_tdata       Pointer to receive the UPDATE request message to
+ *                      be created.
+ *
+ * @return              PJ_SUCCESS if a UPDATE request with the specified
+ *                      characteristics (e.g. to contain new offer) can be 
+ *                      created.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_update ( pjsip_inv_session *inv,
+                                        const pj_str_t *new_contact,
+                                        const pjmedia_sdp_session *offer,
+                                        pjsip_tx_data **p_tdata );
+
+
+/**
+ * Create an ACK request. Normally ACK request transmission is handled
+ * by the framework. Application only needs to use this function if it
+ * handles the ACK transmission manually, by overriding \a on_send_ack()
+ * callback in #pjsip_inv_callback.
+ *
+ * Note that if the invite session has a pending offer to be answered 
+ * (for example when the last 2xx response to INVITE contains an offer), 
+ * application MUST have set the SDP answer with #pjsip_inv_set_sdp_answer()
+ * prior to creating the ACK request. In this case, the ACK request
+ * will be added with SDP message body.
+ *
+ * @param inv           The invite session.
+ * @param cseq          Mandatory argument to specify the CSeq of the
+ *                      ACK request. This value MUST match the value
+ *                      of the INVITE transaction to be acknowledged.
+ * @param p_tdata       Pointer to receive the ACK request message to
+ *                      be created.
+ *
+ * @return              PJ_SUCCESS if ACK request has been created.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_create_ack(pjsip_inv_session *inv,
+                                          int cseq,
+                                          pjsip_tx_data **p_tdata);
+
+
+/**
+ * Send request or response message in tdata. 
+ *
+ * @param inv           The invite session.
+ * @param tdata         The message to be sent.
+ *
+ * @return              PJ_SUCCESS if transaction can be initiated 
+ *                      successfully to send this message. Note that the
+ *                      actual final state of the transaction itself will
+ *                      be reported later, in on_tsx_state_changed()
+ *                      callback.
+ */
+PJ_DECL(pj_status_t) pjsip_inv_send_msg(pjsip_inv_session *inv,
+                                        pjsip_tx_data *tdata);
+
+
+/**
+ * Get the invite session for the dialog, if any.
+ *
+ * @param dlg           The dialog which invite session is being queried.
+ *
+ * @return              The invite session instance which has been 
+ *                      associated with this dialog, or NULL.
+ */
+PJ_DECL(pjsip_inv_session*) pjsip_dlg_get_inv_session(pjsip_dialog *dlg);
+
+/**
+ * Get the invite session instance associated with transaction tsx, if any.
+ *
+ * @param tsx           The transaction, which invite session is being 
+ *                      queried.
+ *
+ * @return              The invite session instance which has been 
+ *                      associated with this transaction, or NULL.
+ */
+PJ_DECL(pjsip_inv_session*) pjsip_tsx_get_inv_session(pjsip_transaction *tsx);
+
+
+/**
+ * Get state names for INVITE session state.
+ *
+ * @param state         The invite state.
+ *
+ * @return              String describing the state.
+ */
+PJ_DECL(const char *) pjsip_inv_state_name(pjsip_inv_state state);
+
+
+/**
+ * This is a utility function to create SIP body for SDP content.
+ *
+ * @param pool          Pool to allocate memory.
+ * @param sdp           SDP session to be put in the SIP message body.
+ * @param p_body        Pointer to receive SIP message body containing
+ *                      the SDP session.
+ *
+ * @return              PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjsip_create_sdp_body(pj_pool_t *pool,
+                                           pjmedia_sdp_session *sdp,
+                                           pjsip_msg_body **p_body);
+
+/**
+ * This is a utility function to create a multipart body with the
+ * SIP body as the first part.
+ *
+ * @param pool          Pool to allocate memory.
+ * @param sdp           SDP session to be put in the SIP message body.
+ * @param p_body        Pointer to receive SIP message body containing
+ *                      the SDP session.
+ *
+ * @return              PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjsip_create_multipart_sdp_body( pj_pool_t *pool,
+                                           pjmedia_sdp_session *sdp,
+                                           pjsip_msg_body **p_body);
+
+/**
+ * Retrieve SDP information from a message body. Application should
+ * prefer to use this function rather than parsing the SDP manually since
+ * this function supports multipart message body.
+ *
+ * This function will only parse the SDP once, the first time it is called
+ * on the same message. Subsequent call on the same message will just pick
+ * up the already parsed SDP from the message.
+ *
+ * @param pool               Pool to allocate memory.
+ * @param body               The message body.
+ * @param msg_media_type     From the rdata or tdata Content-Type header, if available.
+ *                           If NULL, the content_type from the body will be used.
+ * @param search_media_type  The media type to search for.
+ *                           If NULL, "application/sdp" will be used.
+ *
+ * @return                   The SDP info.
+ */
+PJ_DECL(pjsip_sdp_info*) pjsip_get_sdp_info(pj_pool_t *pool,
+                                           pjsip_msg_body *body,
+                                           pjsip_media_type *msg_media_type,
+                                           const pjsip_media_type *search_media_type);
+
+/**
+ * Retrieve SDP information from an incoming message. Application should
+ * prefer to use this function rather than parsing the SDP manually since
+ * this function supports multipart message body.
+ *
+ * This function will only parse the SDP once, the first time it is called
+ * on the same message. Subsequent call on the same message will just pick
+ * up the already parsed SDP from the message.
+ *
+ * @param rdata         The incoming message.
+ *
+ * @return              The SDP info.
+ */
+PJ_DECL(pjsip_rdata_sdp_info*) pjsip_rdata_get_sdp_info(pjsip_rx_data *rdata);
+
+
+/**
+ * Retrieve SDP information from an incoming message. Application should
+ * prefer to use this function rather than parsing the SDP manually since
+ * this function supports multipart message body.
+ *
+ * This function will only parse the SDP once, the first time it is called
+ * on the same message. Subsequent call on the same message will just pick
+ * up the already parsed SDP from the message.
+ *
+ * @param rdata               The incoming message.
+ * @param search_media_type   The SDP media type to search for.
+ *                            If NULL, "application/sdp" will be used.
+ *
+ * @return                    The SDP info.
+ */
+PJ_DECL(pjsip_rdata_sdp_info*) pjsip_rdata_get_sdp_info2(
+                                            pjsip_rx_data *rdata,
+                                            const pjsip_media_type *search_media_type);
+
+/**
+ * Retrieve SDP information from an outgoing message. Application should
+ * prefer to use this function rather than parsing the SDP manually since
+ * this function supports multipart message body.
+ *
+ * This function will only parse the SDP once, the first time it is called
+ * on the same message. Subsequent call on the same message will just pick
+ * up the already parsed SDP from the message.
+ *
+ * @param tdata    The outgoing message.
+ *
+ * @return         The SDP info.
+ */
+PJ_DECL(pjsip_tdata_sdp_info*) pjsip_tdata_get_sdp_info(pjsip_tx_data *tdata);
+
+/**
+ * Retrieve SDP information from an outgoing message. Application should
+ * prefer to use this function rather than parsing the SDP manually since
+ * this function supports multipart message body.
+ *
+ * This function will only parse the SDP once, the first time it is called
+ * on the same message. Subsequent call on the same message will just pick
+ * up the already parsed SDP from the message.
+ *
+ * @param tdata               The outgoing message.
+ * @param search_media_type   The SDP media type to search for.
+ *                            If NULL, "application/sdp" will be used.
+ *
+ * @return                    The SDP info.
+ */
+PJ_DECL(pjsip_tdata_sdp_info*) pjsip_tdata_get_sdp_info2(
+                                            pjsip_tx_data *tdata,
+                                            const pjsip_media_type *search_media_type);
+
+
+PJ_END_DECL
+
+/**
+ * @}
+ */
+
+
+#endif  /* __SIP_INVITE_SESSION_H__ */