Group PJSIP_INV

group PJSIP_INV

Provides INVITE session management.

The INVITE session uses the Base 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 SIP Event Notification (RFC 3265) Module). The INVITE session manages the life-time of the session, and also manages the SDP negotiation.

Application must link with pjsip-ua static library to use this API.

More detailed information is explained in PJSIP Developer’s Guide 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 PJSUA API - High Level Softphone API for this purpose.

Typedefs

typedefPJ_BEGIN_DECL struct pjsip_inv_session pjsip_inv_session

See

pjsip_inv_session

Enums

enum pjsip_inv_state

This enumeration describes invite session state.

Values:

enumerator PJSIP_INV_STATE_NULL

Before INVITE is sent or received

enumerator PJSIP_INV_STATE_CALLING

After INVITE is sent

enumerator PJSIP_INV_STATE_INCOMING

After INVITE is received.

enumerator PJSIP_INV_STATE_EARLY

After response with To tag.

enumerator PJSIP_INV_STATE_CONNECTING

After 2xx is sent/received.

enumerator PJSIP_INV_STATE_CONFIRMED

After ACK is sent/received.

enumerator PJSIP_INV_STATE_DISCONNECTED

Session is terminated.

enum pjsip_inv_option

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.

Values:

enumerator PJSIP_INV_SUPPORT_100REL

Indicate support for reliable provisional response extension

enumerator PJSIP_INV_SUPPORT_TIMER

Indicate support for session timer extension.

enumerator PJSIP_INV_SUPPORT_UPDATE

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.

enumerator PJSIP_INV_SUPPORT_ICE

Indicate support for ICE

enumerator PJSIP_INV_REQUIRE_ICE

Require ICE support.

enumerator PJSIP_INV_REQUIRE_100REL

Require reliable provisional response extension.

enumerator PJSIP_INV_REQUIRE_TIMER

Require session timer extension.

enumerator PJSIP_INV_ALWAYS_USE_TIMER

Session timer extension will always be used even when peer doesn’t support/want session timer.

Functions

pj_status_t pjsip_inv_usage_init(pjsip_endpoint *endpt, const pjsip_inv_callback *cb)

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.

Parameters
  • endpt – The endpoint instance.

  • cb – Callback structure.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsip_module *pjsip_inv_usage_instance(void)

Get the INVITE usage module instance.

Returns

PJ_SUCCESS on success, or the appropriate error code.

void pjsip_inv_usage_dump(void)

Dump user agent contents (e.g. all dialogs).

pj_status_t pjsip_inv_create_uac(pjsip_dialog *dlg, const pjmedia_sdp_session *local_sdp, unsigned options, pjsip_inv_session **p_inv)

Create UAC invite session for the specified dialog in dlg.

Parameters
  • dlg – The dialog which will be used by this invite session.

  • 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.

  • options – The options argument is bitmask combination of SIP features in pjsip_inv_option enumeration.

  • p_inv – On successful return, the invite session will be put in this argument.

Returns

The function will return PJ_SUCCESS if it can create the session. Otherwise the appropriate error status will be returned on failure.

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)

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.

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).

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()

Parameters
  • rdata – The incoming INVITE request.

  • 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.

  • 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.

  • 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.

  • 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.

  • tdata – If this argument is not NULL, this function will create the appropriate non-2xx final response message when the verification fails.

Returns

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.

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 to specify the parsed SDP in the offer argument. This is useful to avoid having to re-parse the SDP in the incoming request.

See

pjsip_inv_verify_request()

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)

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 offer argument and a temporary pool in the tmp_pool argument. This is useful if application no longer has access to the rdata.

See

pjsip_inv_verify_request()

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)

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.

Parameters
  • dlg – The dialog to be used.

  • 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.

  • 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.

  • options – The options argument is bitmask combination of SIP features in pjsip_inv_option enumeration.

  • p_inv – Pointer to receive the newly created invite session.

Returns

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_status_t pjsip_inv_add_ref(pjsip_inv_session *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.

Parameters

inv – The INVITE session.

Returns

PJ_SUCCESS if the INVITE session reference counter was increased.

pj_status_t pjsip_inv_dec_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.

Parameters

inv – The INVITE session.

Returns

PJ_SUCCESS if the INVITE session reference counter was decreased. A status PJ_EGONE will be returned to inform that session is destroyed.

pj_status_t pjsip_inv_terminate(pjsip_inv_session *inv, int st_code, pj_bool_t notify)

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.

Parameters
  • inv – The invite session.

  • st_code – Status code for the reason of the termination.

  • notify – If set to non-zero, then on_state_changed() callback will be called.

Returns

PJ_SUCCESS if the INVITE session has been terminated.

pj_status_t pjsip_inv_uac_restart(pjsip_inv_session *inv, pj_bool_t new_offer)

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.

Parameters
  • inv – The invite session.

  • new_offer – Should be set to PJ_TRUE since the application will restart the session.

Returns

PJ_SUCCESS on successful operation.

pj_status_t pjsip_inv_process_redirect(pjsip_inv_session *inv, pjsip_redirect_op cmd, pjsip_event *e)

Accept or reject redirection response. Application MUST call this function after it signaled PJSIP_REDIRECT_PENDING in the 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 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 on_redirected() callback may also be called before this function returns if there is another target to try.

Parameters
  • inv – The invite session.

  • cmd – Redirection operation. The semantic of this argument is similar to the description in the on_redirected() callback, except that the PJSIP_REDIRECT_PENDING is not accepted here.

  • e – Should be set to NULL.

Returns

PJ_SUCCESS on successful operation.

pj_status_t pjsip_inv_invite(pjsip_inv_session *inv, pjsip_tx_data **p_tdata)

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.

Parameters
  • inv – The UAC invite session.

  • p_tdata – The initial INVITE request will be put in this argument if it can be created successfully.

Returns

PJ_SUCCESS if the INVITE request can be created.

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 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_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)

Create a response message to an INVITE request.

Parameters
  • inv – The UAS invite session.

  • st_code – The st_code contains the status code to be sent, which may be a provisional or final response.

  • 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.

  • 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.

  • p_tdata – Pointer to receive the response message created by this function.

Returns

PJ_SUCCESS if response message was created successfully.

pj_status_t pjsip_inv_set_local_sdp(pjsip_inv_session *inv, const pjmedia_sdp_session *sdp)

Set local offer or answer depending on negotiator state (it may also create a negotiator if it doesn’t exist yet).

Parameters
  • inv – The invite session.

  • sdp – The SDP description which will be set as an offer/answer to remote.

Returns

PJ_SUCCESS if local offer/answer can be accepted by SDP negotiator.

pj_status_t pjsip_inv_set_sdp_answer(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).

Parameters
  • inv – The invite session.

  • sdp – The SDP description which will be set as answer to remote.

Returns

PJ_SUCCESS if local answer can be accepted by SDP negotiator.

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 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 st_code and optional status text in 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 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.

Parameters
  • inv – The invite session.

  • st_code – Status code to be used for terminating the session.

  • st_text – Optional status text.

  • 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.

Returns

PJ_SUCCESS if termination is initiated.

pj_status_t pjsip_inv_cancel_reinvite(pjsip_inv_session *inv, 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 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.

Parameters
  • inv – The invite session.

  • 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.

Returns

PJ_SUCCESS if termination is initiated.

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 a re-INVITE request.

Parameters
  • inv – The invite session.

  • 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.

  • 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.

  • p_tdata – Pointer to receive the re-INVITE request message to be created.

Returns

PJ_SUCCESS if a re-INVITE request with the specified characteristics (e.g. to contain new offer) can be created.

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 UPDATE request to initiate new SDP offer.

Parameters
  • inv – The invite session.

  • 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.

  • offer – Offer to be sent to remote. This argument is mandatory.

  • p_tdata – Pointer to receive the UPDATE request message to be created.

Returns

PJ_SUCCESS if a UPDATE request with the specified characteristics (e.g. to contain new offer) can be created.

pj_status_t pjsip_inv_create_ack(pjsip_inv_session *inv, int cseq, 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 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.

Parameters
  • inv – The invite session.

  • cseq – Mandatory argument to specify the CSeq of the ACK request. This value MUST match the value of the INVITE transaction to be acknowledged.

  • p_tdata – Pointer to receive the ACK request message to be created.

Returns

PJ_SUCCESS if ACK request has been created.

pj_status_t pjsip_inv_send_msg(pjsip_inv_session *inv, pjsip_tx_data *tdata)

Send request or response message in tdata.

Parameters
  • inv – The invite session.

  • tdata – The message to be sent.

Returns

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.

pjsip_inv_session *pjsip_dlg_get_inv_session(pjsip_dialog *dlg)

Get the invite session for the dialog, if any.

Parameters

dlg – The dialog which invite session is being queried.

Returns

The invite session instance which has been associated with this dialog, or NULL.

pjsip_inv_session *pjsip_tsx_get_inv_session(pjsip_transaction *tsx)

Get the invite session instance associated with transaction tsx, if any.

Parameters

tsx – The transaction, which invite session is being queried.

Returns

The invite session instance which has been associated with this transaction, or NULL.

const char *pjsip_inv_state_name(pjsip_inv_state state)

Get state names for INVITE session state.

Parameters

state – The invite state.

Returns

String describing the state.

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 SIP body for SDP content.

Parameters
  • pool – Pool to allocate memory.

  • sdp – SDP session to be put in the SIP message body.

  • p_body – Pointer to receive SIP message body containing the SDP session.

Returns

PJ_SUCCESS on success.

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.

Parameters

rdata – The incoming message.

Returns

The SDP info.

struct pjsip_inv_on_rx_offer_cb_param
#include <sip_inv.h>

Structure to hold parameters when calling the callback #on_rx_offer2().

struct pjsip_inv_callback
#include <sip_inv.h>

This structure contains callbacks to be registered by application to receieve notifications from the framework about various events in the invite session.

struct pjsip_inv_session
#include <sip_inv.h>

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_rdata_sdp_info
#include <sip_inv.h>

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.