100rel/PRACK - Reliability of Provisional Responses

PRACK - Reliability of Provisional Responses. More...

Functions
const pjsip_method *	pjsip_get_prack_method (void)
pj_status_t	pjsip_100rel_init_module (pjsip_endpoint *endpt)
pj_status_t	pjsip_100rel_attach (pjsip_inv_session *inv)
pj_bool_t	pjsip_100rel_is_reliable (pjsip_rx_data *rdata)
pj_status_t	pjsip_100rel_create_prack (pjsip_inv_session *inv, pjsip_rx_data *rdata, pjsip_tx_data **p_tdata)
pj_status_t	pjsip_100rel_send_prack (pjsip_inv_session *inv, pjsip_tx_data *tdata)
pj_status_t	pjsip_100rel_on_rx_prack (pjsip_inv_session *inv, pjsip_rx_data *rdata)
pj_status_t	pjsip_100rel_tx_response (pjsip_inv_session *inv, pjsip_tx_data *tdata)
pj_status_t	pjsip_100rel_end_session (pjsip_inv_session *inv)

Variables
const pjsip_method	pjsip_prack_method

Detailed Description

This module provides management of Reliability of Provisional Responses (100rel and PRACK), as described in RFC 3262.

Other than the pjsip_100rel_init_module() function, the 100rel API exported by this module are not intended to be used by application, but rather they will be invoked by the INVITE Session.

Using Reliable Provisional Response

Initializing 100rel Module

Application must explicitly initialize 100rel module by calling pjsip_100rel_init_module() in application initialization function.

Once the 100rel module is initialized, it will register PRACK method in Allow header, and 100rel tag in Supported header.

Using 100rel in a Session

For UAC, 100rel support will be enabled in the session if 100rel support is enabled in the library (default is yes). Outgoing INVITE request will include 100rel tag in Supported header and PRACK method in Allow header. When callee endpoint sends reliable provisional responses, the UAC will automatically send PRACK request to acknowledge the response. If callee endpoint doesn't send reliable provisional response, the response will be handled using normal, non-100rel procedure (that is, PRACK will not be sent).

If the UAC wants to mandate 100rel support, it can specify PJSIP_INV_REQUIRE_100REL in the options argument when calling pjsip_inv_create_uac(). In this case, PJSIP will add 100rel tag in the Require header of the outgoing INVITE request.

For UAS, if it wants to support 100rel but not to mandate it, it must specify PJSIP_INV_SUPPORT_100REL flag in the options argument when calling pjsip_inv_verify_request(), and pass the same options variable when calling pjsip_inv_verify_request. If UAC had specified 100rel in it's list of extensions in Require header, the UAS will send provisional responses reliably. If UAC only listed 100rel in its Supported header but not in Require header, or if UAC does not list 100rel support at all, the UAS WILL NOT send provisional responses reliably. The snippet below can be used to accomplish this task:

 unsigned options = 0;

 options |= PJSIP_INV_SUPPORT_100REL;

 status = pjsip_inv_verify_request(rdata, &options, answer, NULL,
                                   endpt, &resp);
 if (status != PJ_SUCCESS) {
     // INVITE request cannot be handled.
     // Reject the request with the response in resp.
     ...
     return;
 }

 // Create UAS dialog, populate Contact header, etc.
 ...

 // Create UAS invite session
 status = pjsip_inv_create_uas( dlg, rdata, answer, options, &inv);

 ..

For another requirement, if UAS wants to mandate 100rel support, it can specify PJSIP_INV_REQUIRE_100REL flag when calling pjsip_inv_verify_request(), and pass the options when calling pjsip_inv_verify_request. In this case, 100rel extension will be used if UAC specifies 100rel in its Supported header. If UAC does not list 100rel in Supported header, the incoming INVITE request will be rejected with 421 (Extension Required) response. For the sample code, it should be identical to the snippet above, except that application must specify PJSIP_INV_REQUIRE_100REL flag in the options instead of PJSIP_INV_SUPPORT_100REL.

For yet another requirement, if UAS does not want to support 100rel extension, it can reject incoming INVITE request with 420 (Bad Extension) response whenever incoming INVITE request has 100rel tag in its Require header. This can be done by specifying zero as the options when calling pjsip_inv_verify_request().

Function Documentation

pjsip_get_prack_method()

const pjsip_method * pjsip_get_prack_method

(

void

)

Get pjsip_invite_method constant.

pjsip_100rel_init_module()

pj_status_t pjsip_100rel_init_module

(

pjsip_endpoint *

endpt

)

Initialize 100rel module. This function must be called once during application initialization, to register 100rel module to SIP endpoint.

Parameters

endpt

The SIP endpoint instance.

Returns

PJ_SUCCESS if module is successfully initialized.

pjsip_100rel_attach()

pj_status_t pjsip_100rel_attach

(

pjsip_inv_session *

inv

)

Add 100rel support to the specified invite session. This function will be called internally by the invite session if it detects that the session needs 100rel support.

Parameters

inv	The invite session.

Returns

PJ_SUCCESS on successful.

pjsip_100rel_is_reliable()

pj_bool_t pjsip_100rel_is_reliable

(

pjsip_rx_data *

rdata

)

Check if incoming response has reliable provisional response feature.

Parameters

rdata

Receive data buffer containing the response.

Returns

PJ_TRUE if the provisional response is reliable.

pjsip_100rel_create_prack()

pj_status_t pjsip_100rel_create_prack	(	pjsip_inv_session *	inv,
		pjsip_rx_data *	rdata,
		pjsip_tx_data **	p_tdata
	)

Create PRACK request for the incoming reliable provisional response. Note that PRACK request MUST be sent using pjsip_100rel_send_prack().

Parameters

inv	The invite session.
rdata	The incoming reliable provisional response.
p_tdata	Upon return, it will be initialized with the PRACK request.

Returns

PJ_SUCCESS on successful.

pjsip_100rel_send_prack()

pj_status_t pjsip_100rel_send_prack	(	pjsip_inv_session *	inv,
		pjsip_tx_data *	tdata
	)

Send PRACK request.

Parameters

inv	The invite session.
tdata	The PRACK request.

Returns

PJ_SUCCESS on successful.

pjsip_100rel_on_rx_prack()

pj_status_t pjsip_100rel_on_rx_prack	(	pjsip_inv_session *	inv,
		pjsip_rx_data *	rdata
	)

Handle incoming PRACK request.

Parameters

inv	The invite session.
rdata	Incoming PRACK request.

Returns

PJ_SUCCESS on successful.

pjsip_100rel_tx_response()

pj_status_t pjsip_100rel_tx_response	(	pjsip_inv_session *	inv,
		pjsip_tx_data *	tdata
	)

Transmit INVITE response (provisional or final) reliably according to 100rel specification. The 100rel module will take care of retransmitting or enqueueing the response according to the current state of the reliable response processing. This function will be called internally by invite session.

Parameters

inv	The invite session.
tdata	The INVITE response.

Returns

PJ_SUCCESS on successful.

pjsip_100rel_end_session()

pj_status_t pjsip_100rel_end_session

(

pjsip_inv_session *

inv

)

Notify 100rel module that the invite session has been disconnected.

Parameters

inv	The invite session.

Returns

PJ_SUCCESS on successful.

References PJ_END_DECL.

Variable Documentation

pjsip_prack_method

const pjsip_method pjsip_prack_method

PRACK method constant.

See also

pjsip_get_prack_method()