libpjproject-dev 2.7.2~dfsg-1 / usr / include / pjsip-ua / sip_inv.h

/* $Id: sip_inv.h 5641 2017-08-16 04:53:44Z ming $ */
/* 
 * 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 
 * receieve 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.
     *
     * This callback is mandatory.
     *
     * @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, 
     * 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 creates the ACK request
     *
     * 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, and instead automatic
     * retransmission of this ACK request from the cache will be done
     * by the framework.
     *
     * 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

};

/* 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
 * http://trac.pjsip.org/repos/ticket/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.	    */
    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. */
};


/**
 * This structure represents SDP information in a pjsip_rx_data. Application
 * retrieve this information by calling #pjsip_rdata_get_sdp_info(). This
 * mechanism supports multipart message body.
 */
typedef struct pjsip_rdata_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_rdata_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, to let remote UAS specifies 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.
 */
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_create_sdp_body()
 * 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);

/**
 * 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);


PJ_END_DECL

/**
 * @}
 */


#endif	/* __SIP_INVITE_SESSION_H__ */