INVITE Session
[User Agent Library]

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 C/C++ and Python for this purpose.

Typedef Documentation

typedef typedefPJ_BEGIN_DECL struct pjsip_inv_session pjsip_inv_session

See also:: pjsip_inv_session

Enumeration Type Documentation

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.

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_REQUIRE_100REL	Require reliable provisional response extension.
PJSIP_INV_REQUIRE_TIMER	Require session timer extension.

Function Documentation

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

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.

See also:: 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()

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_options 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_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_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 the initial INVITE request. This function can only be called for the initial INVITE request, as subsequent re-INVITE request will be answered automatically.

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_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, or a BYE request. 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.

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.

Returns:: PJ_SUCCESS if termination message can be created.

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.

INVITE Session [User Agent Library]

Detailed Description

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

Enumeration Type Documentation

Function Documentation

INVITE Session
[User Agent Library]