BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJSIP Reference

SIP REFER (RFC 3515) for Call Transfer etc.

SIP REFER dialog usage (call transfer, etc.) More...

Functions

const pjsip_methodpjsip_get_refer_method (void)
 
pj_status_t pjsip_xfer_init_module (pjsip_endpoint *endpt)
 
pj_status_t pjsip_xfer_create_uac (pjsip_dialog *dlg, const pjsip_evsub_user *user_cb, pjsip_evsub **p_evsub)
 
pj_status_t pjsip_xfer_create_uas (pjsip_dialog *dlg, const pjsip_evsub_user *user_cb, pjsip_rx_data *rdata, pjsip_evsub **p_evsub)
 
pj_status_t pjsip_xfer_initiate (pjsip_evsub *sub, const pj_str_t *refer_to_uri, pjsip_tx_data **p_tdata)
 
pj_status_t pjsip_xfer_accept (pjsip_evsub *sub, pjsip_rx_data *rdata, int st_code, const pjsip_hdr *hdr_list)
 
pj_status_t pjsip_xfer_notify (pjsip_evsub *sub, pjsip_evsub_state state, int xfer_st_code, const pj_str_t *xfer_st_text, pjsip_tx_data **p_tdata)
 
pj_status_t pjsip_xfer_current_notify (pjsip_evsub *sub, pjsip_tx_data **p_tdata)
 
pj_status_t pjsip_xfer_send_request (pjsip_evsub *sub, pjsip_tx_data *tdata)
 

Variables

PJ_BEGIN_DECL const pjsip_method pjsip_refer_method
 

Detailed Description

This describes a generic handling of SIP REFER request. The SIP REFER request is described in RFC 3515, and commonly used to perform call transfer functionality. Other types of SIP REFER usages are described in draft-worley-sip-many-refers-00 draft, for example:

  • Remote Dial: where UAC sends REFER to instruct REFER recipient to initiate an INVITE session to some target.

A REFER request can be sent inside or outside existing dialog context, although for call transfer case, it is more common to send REFER inside existing INVITE session context. PJSIP supports both sending REFER request inside or outside dialog context.

The REFER framework uses SIP Event Notification (RFC 3265) Module to manage the event subscription created by the REFER request. Because of this, application must link with pjsip-ua AND pjsip-simple static libraries to use REFER functionality.

Reference:

Function Documentation

const pjsip_method* pjsip_get_refer_method ( void  )

Get REFER method constant

pj_status_t pjsip_xfer_init_module ( pjsip_endpoint endpt)

Initialize the REFER subsystem. This currently does very little (only register REFER as supported method).

pj_status_t pjsip_xfer_create_uac ( pjsip_dialog dlg,
const pjsip_evsub_user user_cb,
pjsip_evsub **  p_evsub 
)

Create transferer (sender of REFER request).

Parameters
dlgThe underlying dialog to use.
user_cbPointer to callbacks to receive presence subscription events.
p_evsubPointer to receive the presence subscription session.
Returns
PJ_SUCCESS on success.
pj_status_t pjsip_xfer_create_uas ( pjsip_dialog dlg,
const pjsip_evsub_user user_cb,
pjsip_rx_data rdata,
pjsip_evsub **  p_evsub 
)

Create transferee (receiver of REFER request).

Parameters
dlgThe underlying dialog to use.
user_cbPointer to callbacks to receive presence subscription events.
rdataThe incoming SUBSCRIBE request that creates the event subscription.
p_evsubPointer to receive the presence subscription session.
Returns
PJ_SUCCESS on success.
pj_status_t pjsip_xfer_initiate ( pjsip_evsub sub,
const pj_str_t refer_to_uri,
pjsip_tx_data **  p_tdata 
)

Call this function to create request to initiate REFER subscription, to refresh subscription, or to unsubscribe. For request other than the initial REFER request, "refer_to_uri" argument may be NULL.

Parameters
subClient subscription instance.
refer_to_uriURI to be put to the Refer-To header. This argument may be NULL for subsequent REFER requests.
p_tdataPointer to receive the request.
Returns
PJ_SUCCESS on success.
pj_status_t pjsip_xfer_accept ( pjsip_evsub sub,
pjsip_rx_data rdata,
int  st_code,
const pjsip_hdr hdr_list 
)

Accept the incoming REFER request by sending 2xx response.

Parameters
subServer subscription instance.
rdataThe incoming subscription request message.
st_codeStatus code, which MUST be 2xx.
hdr_listOptional list of headers to be added in the response.
Returns
PJ_SUCCESS on success.
pj_status_t pjsip_xfer_notify ( pjsip_evsub sub,
pjsip_evsub_state  state,
int  xfer_st_code,
const pj_str_t xfer_st_text,
pjsip_tx_data **  p_tdata 
)

For notifier, create NOTIFY request to subscriber, and set the state of the subscription.

Parameters
subThe server subscription (notifier) instance.
stateNew state to set.
xfer_st_codeThe call status code to be reported with the NOTIFY request.
xfer_st_textOptional call status text to be reported with the NOTIFY request. If the value is NULL, default status text will be used.
p_tdataPointer to receive the request.
Returns
PJ_SUCCESS on success.
pj_status_t pjsip_xfer_current_notify ( pjsip_evsub sub,
pjsip_tx_data **  p_tdata 
)

Create NOTIFY request to reflect current subscription status. Application can only call this function after it has sent NOTIFY before. This will also re-send the last "message/sipfrag" body that was sent in the previous NOTIFY.

Parameters
subServer subscription object.
p_tdataPointer to receive request.
Returns
PJ_SUCCESS on success.
pj_status_t pjsip_xfer_send_request ( pjsip_evsub sub,
pjsip_tx_data tdata 
)

Send request message that was previously created with initiate(), notify(), or current_notify(). Application may also send request created with other functions, e.g. authentication. But the request MUST be either request that creates/refresh subscription or NOTIFY request.

Parameters
subThe event subscription object.
tdataRequest message to be send.
Returns
PJ_SUCCESS on success.

Variable Documentation

PJ_BEGIN_DECL const pjsip_method pjsip_refer_method

Declaration for REFER method constant.

 


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