BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJSIP Reference

100rel/PRACK - Reliability of Provisional Responses

PRACK - Reliability of Provisional Responses. More...

Functions

const pjsip_methodpjsip_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

PJ_BEGIN_DECL 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

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
endptThe 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
invThe 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
rdataReceive 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
invThe invite session.
rdataThe incoming reliable provisional response.
p_tdataUpon 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
invThe invite session.
tdataThe 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
invThe invite session.
rdataIncoming 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
invThe invite session.
tdataThe 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
invThe invite session.
Returns
PJ_SUCCESS on successful.

Variable Documentation

PJ_BEGIN_DECL const pjsip_method pjsip_prack_method

PRACK method constant.

See also
pjsip_get_prack_method()

 


PJSIP Open Source, high performance, small footprint, and very very portable SIP stack
Copyright (C) 2006-2008 Teluu Inc.