Provides INVITE session management. More...

Data Structures
struct	pjsip_inv_on_rx_offer_cb_param

struct	pjsip_inv_callback

struct	pjsip_inv_session

struct	pjsip_sdp_info

Typedefs
typedef pjsip_sdp_info	pjsip_rdata_sdp_info

typedef pjsip_sdp_info	pjsip_tdata_sdp_info

Enumerations
enum	pjsip_inv_state { PJSIP_INV_STATE_NULL , PJSIP_INV_STATE_CALLING , PJSIP_INV_STATE_INCOMING , PJSIP_INV_STATE_EARLY , PJSIP_INV_STATE_CONNECTING , PJSIP_INV_STATE_CONFIRMED , PJSIP_INV_STATE_DISCONNECTED }

enum	pjsip_inv_option { PJSIP_INV_SUPPORT_100REL = 1 , PJSIP_INV_SUPPORT_TIMER = 2 , PJSIP_INV_SUPPORT_UPDATE = 4 , PJSIP_INV_SUPPORT_ICE = 8 , PJSIP_INV_REQUIRE_ICE = 16 , PJSIP_INV_REQUIRE_100REL = 32 , PJSIP_INV_REQUIRE_TIMER = 64 , PJSIP_INV_ALWAYS_USE_TIMER = 128 , PJSIP_INV_SUPPORT_TRICKLE_ICE = 256 , PJSIP_INV_REQUIRE_TRICKLE_ICE = 512 }

Functions
pj_status_t	pjsip_inv_usage_init (pjsip_endpoint endpt, const pjsip_inv_callback cb)

pjsip_module *	pjsip_inv_usage_instance (void)

void	pjsip_inv_usage_dump (void)

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

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)

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)

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)

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)

pj_status_t	pjsip_inv_add_ref (pjsip_inv_session *inv)

pj_status_t	pjsip_inv_dec_ref (pjsip_inv_session *inv)

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

pj_status_t	pjsip_inv_uac_restart (pjsip_inv_session *inv, pj_bool_t new_offer)

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

pj_status_t	pjsip_inv_invite (pjsip_inv_session inv, pjsip_tx_data *p_tdata)

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)

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)

pj_status_t	pjsip_inv_set_local_sdp (pjsip_inv_session inv, const pjmedia_sdp_session sdp)

pj_status_t	pjsip_inv_set_sdp_answer (pjsip_inv_session inv, const pjmedia_sdp_session sdp)

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)

pj_status_t	pjsip_inv_cancel_reinvite (pjsip_inv_session inv, pjsip_tx_data *p_tdata)

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)

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)

pj_status_t	pjsip_inv_create_ack (pjsip_inv_session inv, int cseq, pjsip_tx_data *p_tdata)

pj_status_t	pjsip_inv_send_msg (pjsip_inv_session inv, pjsip_tx_data tdata)

pjsip_inv_session *	pjsip_dlg_get_inv_session (pjsip_dialog *dlg)

pjsip_inv_session *	pjsip_tsx_get_inv_session (pjsip_transaction *tsx)

const char *	pjsip_inv_state_name (pjsip_inv_state state)

pj_status_t	pjsip_create_sdp_body (pj_pool_t pool, pjmedia_sdp_session sdp, pjsip_msg_body **p_body)

pj_status_t	pjsip_create_multipart_sdp_body (pj_pool_t pool, pjmedia_sdp_session sdp, pjsip_msg_body **p_body)

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)

pjsip_rdata_sdp_info *	pjsip_rdata_get_sdp_info (pjsip_rx_data *rdata)

pjsip_rdata_sdp_info *	pjsip_rdata_get_sdp_info2 (pjsip_rx_data rdata, const pjsip_media_type search_media_type)

pjsip_tdata_sdp_info *	pjsip_tdata_get_sdp_info (pjsip_tx_data *tdata)

pjsip_tdata_sdp_info *	pjsip_tdata_get_sdp_info2 (pjsip_tx_data tdata, const pjsip_media_type search_media_type)

Detailed Description

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.

Typedef Documentation

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

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

Enumeration Type Documentation

◆ pjsip_inv_state

enum pjsip_inv_state

This enumeration describes invite session state.

Enumerator
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_option

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.

Enumerator
PJSIP_INV_SUPPORT_100REL	Indicate support for reliable provisional response extension
PJSIP_INV_SUPPORT_TIMER	Indicate support for session timer extension.
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.
PJSIP_INV_SUPPORT_ICE	Indicate support for ICE
PJSIP_INV_REQUIRE_ICE	Require ICE support.
PJSIP_INV_REQUIRE_100REL	Require reliable provisional response extension.
PJSIP_INV_REQUIRE_TIMER	Require session timer extension.
PJSIP_INV_ALWAYS_USE_TIMER	Session timer extension will always be used even when peer doesn't support/want session timer.
PJSIP_INV_SUPPORT_TRICKLE_ICE	Indicate support for trickle ICE
PJSIP_INV_REQUIRE_TRICKLE_ICE	Require trickle ICE support.

Function Documentation

◆ pjsip_inv_usage_init()

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

pjsip_module * pjsip_inv_usage_instance ( void )

Get the INVITE usage module instance.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsip_inv_usage_dump()

void pjsip_inv_usage_dump ( void )

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

◆ pjsip_inv_create_uac()

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.

◆ pjsip_inv_verify_request()

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.

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.

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

Parameters

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.

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

◆ pjsip_inv_verify_request2()

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

◆ pjsip_inv_verify_request3()

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

◆ pjsip_inv_create_uas()

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.

◆ pjsip_inv_add_ref()

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.

◆ pjsip_inv_dec_ref()

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.

◆ pjsip_inv_terminate()

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.

◆ pjsip_inv_uac_restart()

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.

◆ pjsip_inv_process_redirect()

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.

◆ pjsip_inv_invite()

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.

◆ pjsip_inv_initial_answer()

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.

◆ pjsip_inv_answer()

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.

◆ pjsip_inv_set_local_sdp()

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.

◆ pjsip_inv_set_sdp_answer()

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.

◆ pjsip_inv_end_session()

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.

◆ pjsip_inv_cancel_reinvite()

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.

◆ pjsip_inv_reinvite()

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.

◆ pjsip_inv_update()

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.

◆ pjsip_inv_create_ack()

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.

◆ pjsip_inv_send_msg()

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

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

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.

◆ pjsip_inv_state_name()

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.

◆ pjsip_create_sdp_body()

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

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

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

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

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.

References PJ_END_DECL.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ pjsip_rdata_sdp_info

◆ pjsip_tdata_sdp_info

Enumeration Type Documentation

◆ pjsip_inv_state

◆ pjsip_inv_option

Function Documentation

◆ pjsip_inv_usage_init()

◆ pjsip_inv_usage_instance()

◆ pjsip_inv_usage_dump()

◆ pjsip_inv_create_uac()

◆ pjsip_inv_verify_request()

◆ pjsip_inv_verify_request2()

◆ pjsip_inv_verify_request3()

◆ pjsip_inv_create_uas()

◆ pjsip_inv_add_ref()

◆ pjsip_inv_dec_ref()

◆ pjsip_inv_terminate()

◆ pjsip_inv_uac_restart()

◆ pjsip_inv_process_redirect()

◆ pjsip_inv_invite()

◆ pjsip_inv_initial_answer()

◆ pjsip_inv_answer()

◆ pjsip_inv_set_local_sdp()

◆ pjsip_inv_set_sdp_answer()

◆ pjsip_inv_end_session()

◆ pjsip_inv_cancel_reinvite()

◆ pjsip_inv_reinvite()

◆ pjsip_inv_update()

◆ pjsip_inv_create_ack()

◆ pjsip_inv_send_msg()

◆ pjsip_dlg_get_inv_session()

◆ pjsip_tsx_get_inv_session()

◆ pjsip_inv_state_name()

◆ pjsip_create_sdp_body()

◆ pjsip_create_multipart_sdp_body()

◆ pjsip_get_sdp_info()

◆ pjsip_rdata_get_sdp_info()

◆ pjsip_rdata_get_sdp_info2()

◆ pjsip_tdata_get_sdp_info()

◆ pjsip_tdata_get_sdp_info2()