Group PJSUA_XFER

group PJSUA_XFER

SIP REFER dialog usage (call transfer, etc.)

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:

Functions

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
  • dlg – The underlying dialog to use.

  • user_cb – Pointer to callbacks to receive presence subscription events.

  • p_evsub – Pointer 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
  • dlg – The underlying dialog to use.

  • user_cb – Pointer to callbacks to receive presence subscription events.

  • rdata – The incoming SUBSCRIBE request that creates the event subscription.

  • p_evsub – Pointer 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
  • sub – Client subscription instance.

  • refer_to_uri – URI to be put to the Refer-To header. This argument may be NULL for subsequent REFER requests.

  • p_tdata – Pointer 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
  • sub – Server subscription instance.

  • rdata – The incoming subscription request message.

  • st_code – Status code, which MUST be 2xx.

  • hdr_list – Optional 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
  • sub – The server subscription (notifier) instance.

  • state – New state to set.

  • xfer_st_code – The call status code to be reported with the NOTIFY request.

  • xfer_st_text – Optional call status text to be reported with the NOTIFY request. If the value is NULL, default status text will be used.

  • p_tdata – Pointer 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
  • sub – Server subscription object.

  • p_tdata – Pointer 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
  • sub – The event subscription object.

  • tdata – Request message to be send.

Returns

PJ_SUCCESS on success.

Variables

PJ_BEGIN_DECL const pjsip_method pjsip_refer_method

Declaration for REFER method constant.