mirrors
/
pjsip-pjproject
mirror of https://github.com/pjsip/pjproject.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
pjsip-pjproject/pjsip/include/pjsip-ua/sip_inv.h

1225 lines
53 KiB
C
Raw Permalink Blame History

/*
* 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__ */
Reference in New Issue View Git Blame Copy Permalink