Group PJSIP_100REL

group PJSIP_100REL

PRACK - Reliability of Provisional Responses.

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

Functions

const pjsip_method *pjsip_get_prack_method(void): Get pjsip_invite_method constant.

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.

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.

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.

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.

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.

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.

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.

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.

Variables

const pjsip_method pjsip_prack_method

PRACK method constant.