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

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: For backwards compatibility and completeness, pjsip_rdata_sdp_info and pjsip_tdata_sdp_info are typedef’d to pjsip_sdp_info.

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.

enumerator PJSIP_INV_SUPPORT_TRICKLE_ICE: Indicate support for trickle ICE

enumerator PJSIP_INV_REQUIRE_TRICKLE_ICE: Require trickle ICE support.

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, 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.
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 also

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 also

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 also

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.

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.

Parameters:

inv – The UAS invite session.
rdata – The incoming request message.
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.
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.
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_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_inv_set_sdp_answer() 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.

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

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

Parameters:

pool – Pool to allocate memory.
body – The message body.
msg_media_type – From the rdata or tdata Content-Type header, if available. If NULL, the content_type from the body will be used.
search_media_type – The media type to search for. If NULL, “application/sdp” will be used.

Returns:

The SDP info.

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.

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 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.
search_media_type – The SDP media type to search for. If NULL, “application/sdp” will be used.

Returns:

The SDP info.

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.

Parameters:: tdata – The outgoing message.
Returns:: The SDP info.

pjsip_tdata_sdp_info *pjsip_tdata_get_sdp_info2(pjsip_tx_data *tdata, 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.

Parameters:

tdata – The outgoing message.
search_media_type – The SDP media type to search for. If NULL, “application/sdp” will be used.

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

Public Members

const pjmedia_sdp_session *offer: Remote offer.

const pjsip_rx_data *rdata: The received request.

struct pjsip_inv_callback

#include <sip_inv.h>

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

Public Members

void (*on_state_changed)(pjsip_inv_session *inv, pjsip_event *e)

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_new_session)(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_tsx_state_changed)(pjsip_inv_session *inv, pjsip_transaction *tsx, 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_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. 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_offer2)(pjsip_inv_session *inv, struct pjsip_inv_on_rx_offer_cb_param *param)

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.

pj_status_t (*on_rx_reinvite)(pjsip_inv_session *inv, const pjmedia_sdp_session *offer, pjsip_rx_data *rdata)

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

void (*on_create_offer)(pjsip_inv_session *inv, pjmedia_sdp_session **p_offer)

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_media_update)(pjsip_inv_session *inv_ses, pj_status_t status)

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_send_ack)(pjsip_inv_session *inv, pjsip_rx_data *rdata)

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.

pjsip_redirect_op (*on_redirected)(pjsip_inv_session *inv, const pjsip_uri *target, const pjsip_event *e)

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.

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

See also

pjsip_inv_session

Public Members

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?

struct pjsip_sdp_info

#include <sip_inv.h>

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.

Public Members

pj_str_t body: 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_status_t sdp_err: This will contain non-zero if an invalid SDP body is found in the message.

pjmedia_sdp_session *sdp: A parsed and validated SDP body.