SIP REFER (RFC 3515) for Call Transfer etc.
[User Agent Library]

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

Functions
const pjsip_method *	pjsip_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:

• RFC 3515: The Session Initiation Protocol (SIP) Refer Method
• SIP Event Notification (RFC 3265) Module

---

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:

	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.

---

Variable Documentation

PJ_BEGIN_DECL const pjsip_method pjsip_refer_method

Declaration for REFER method constant.