SIP Event Notification (RFC 3265) Module

Core Event Subscription framework, used by presence, call transfer, etc. More...

Modules
	Additional Header Fields

Data Structures
struct	pjsip_evsub_user

Typedefs
typedef struct pjsip_evsub	pjsip_evsub

Enumerations
enum	pjsip_evsub_state {   PJSIP_EVSUB_STATE_NULL , PJSIP_EVSUB_STATE_SENT , PJSIP_EVSUB_STATE_ACCEPTED , PJSIP_EVSUB_STATE_PENDING ,   PJSIP_EVSUB_STATE_ACTIVE , PJSIP_EVSUB_STATE_TERMINATED , PJSIP_EVSUB_STATE_UNKNOWN }
enum	{ PJSIP_EVSUB_NO_EVENT_ID = 1 }

Functions
const pjsip_method *	pjsip_get_subscribe_method (void)
const pjsip_method *	pjsip_get_notify_method (void)
pj_status_t	pjsip_evsub_init_module (pjsip_endpoint *endpt)
pjsip_module *	pjsip_evsub_instance (void)
pj_status_t	pjsip_evsub_register_pkg (pjsip_module *pkg_mod, const pj_str_t *event_name, unsigned expires, unsigned accept_cnt, const pj_str_t accept[])
const pjsip_hdr *	pjsip_evsub_get_allow_events_hdr (const pjsip_module *m)
pj_status_t	pjsip_evsub_create_uac (pjsip_dialog *dlg, const pjsip_evsub_user *user_cb, const pj_str_t *event, unsigned option, pjsip_evsub **p_evsub)
pj_status_t	pjsip_evsub_create_uas (pjsip_dialog *dlg, const pjsip_evsub_user *user_cb, pjsip_rx_data *rdata, unsigned option, pjsip_evsub **p_evsub)
pj_status_t	pjsip_evsub_terminate (pjsip_evsub *sub, pj_bool_t notify)
pjsip_evsub_state	pjsip_evsub_get_state (const pjsip_evsub *sub)
const char *	pjsip_evsub_get_state_name (const pjsip_evsub *sub)
const pj_str_t *	pjsip_evsub_get_termination_reason (const pjsip_evsub *sub)
pj_uint32_t	pjsip_evsub_get_expires (const pjsip_evsub *sub)
pj_status_t	pjsip_evsub_initiate (pjsip_evsub *sub, const pjsip_method *method, pj_uint32_t expires, pjsip_tx_data **p_tdata)
pj_status_t	pjsip_evsub_add_header (pjsip_evsub *sub, const pjsip_hdr *hdr_list)
pj_status_t	pjsip_evsub_accept (pjsip_evsub *sub, pjsip_rx_data *rdata, int st_code, const pjsip_hdr *hdr_list)
pj_status_t	pjsip_evsub_notify (pjsip_evsub *sub, pjsip_evsub_state state, const pj_str_t *state_str, const pj_str_t *reason, pjsip_tx_data **p_tdata)
pj_status_t	pjsip_evsub_current_notify (pjsip_evsub *sub, pjsip_tx_data **p_tdata)
pj_status_t	pjsip_evsub_send_request (pjsip_evsub *sub, pjsip_tx_data *tdata)
pjsip_evsub *	pjsip_tsx_get_evsub (const pjsip_transaction *tsx)
void	pjsip_evsub_set_mod_data (pjsip_evsub *sub, unsigned mod_id, void *data)
void *	pjsip_evsub_get_mod_data (const pjsip_evsub *sub, unsigned mod_id)
pj_status_t	pjsip_evsub_add_ref (pjsip_evsub *sub)
pj_status_t	pjsip_evsub_dec_ref (pjsip_evsub *sub)
void	pjsip_evsub_uas_set_timeout (pjsip_evsub *sub, pj_uint32_t seconds)

Variables
const pjsip_method	pjsip_subscribe_method
const pjsip_method	pjsip_notify_method

Detailed Description

This module provides the implementation of SIP Extension for SIP Specific Event Notification (RFC 3265). It extends PJSIP by supporting SUBSCRIBE and NOTIFY methods.

This module itself is extensible; new event packages can be registered to this module to handle specific extensions (such as presence).

Typedef Documentation

pjsip_evsub

typedef struct pjsip_evsub pjsip_evsub

Opaque type for event subscription session.

Enumeration Type Documentation

pjsip_evsub_state

enum pjsip_evsub_state

This enumeration describes basic subscription state as described in the RFC 3265. The standard specifies that extensions may define additional states. In the case where the state is not known, the subscription state will be set to PJSIP_EVSUB_STATE_UNKNOWN, and the token will be kept in state_str member of the susbcription structure.

Enumerator
PJSIP_EVSUB_STATE_NULL	State is NULL.
PJSIP_EVSUB_STATE_SENT	Client has sent SUBSCRIBE request.
PJSIP_EVSUB_STATE_ACCEPTED	2xx response to SUBSCRIBE has been sent/received.
PJSIP_EVSUB_STATE_PENDING	Subscription is pending.
PJSIP_EVSUB_STATE_ACTIVE	Subscription is active.
PJSIP_EVSUB_STATE_TERMINATED	Subscription is terminated.
PJSIP_EVSUB_STATE_UNKNOWN	Subscription state can not be determined. Application can query the state by calling pjsip_evsub_get_state_name().

anonymous enum

anonymous enum

Some options for the event subscription.

Enumerator
PJSIP_EVSUB_NO_EVENT_ID	If this flag is set, then outgoing request to create subscription will not have id in the Event header (e.g. in REFER request). But if there is an id in the incoming NOTIFY, that id will be used.

Function Documentation

pjsip_get_subscribe_method()

const pjsip_method * pjsip_get_subscribe_method

(

void

)

SUBSCRIBE method constant.

pjsip_get_notify_method()

const pjsip_method * pjsip_get_notify_method

(

void

)

NOTIFY method constant.

pjsip_evsub_init_module()

pj_status_t pjsip_evsub_init_module

(

pjsip_endpoint *

endpt

)

Initialize the event subscription module and register the module to the specified endpoint.

Parameters

endpt

The endpoint instance.

Returns

PJ_SUCCESS if module can be created and registered successfully.

pjsip_evsub_instance()

pjsip_module * pjsip_evsub_instance

(

void

)

Get the event subscription module instance that was previously created and registered to endpoint.

Returns

The event subscription module instance.

pjsip_evsub_register_pkg()

pj_status_t pjsip_evsub_register_pkg	(	pjsip_module *	pkg_mod,
		const pj_str_t *	event_name,
		unsigned	expires,
		unsigned	accept_cnt,
		const pj_str_t	accept[]
	)

Register event package to the event subscription framework.

Parameters

pkg_mod	The module that implements the event package being registered.
event_name	Event package identification.
expires	Default subscription expiration time, in seconds.
accept_cnt	Number of strings in Accept array. The value must not be greater than PJSIP_GENERIC_ARRAY_MAX_COUNT.
accept	Array of Accept value.

Returns

PJ_SUCCESS on success.

pjsip_evsub_get_allow_events_hdr()

const pjsip_hdr * pjsip_evsub_get_allow_events_hdr

(

const pjsip_module *

m

)

Get the Allow-Events header. This header is built based on the packages that are registered to the evsub module.

Parameters

m	Pointer to event subscription module instance, or NULL to use default instance (equal to pjsip_evsub_instance()).

Returns

The Allow-Events header.

pjsip_evsub_create_uac()

pj_status_t pjsip_evsub_create_uac	(	pjsip_dialog *	dlg,
		const pjsip_evsub_user *	user_cb,
		const pj_str_t *	event,
		unsigned	option,
		pjsip_evsub **	p_evsub
	)

Create client subscription session.

Parameters

dlg	The underlying dialog to use.
user_cb	Callback to receive event subscription notifications.
event	Event name.
option	Bitmask of options.
p_evsub	Pointer to receive event subscription instance.

Returns

PJ_SUCCESS on success.

pjsip_evsub_create_uas()

pj_status_t pjsip_evsub_create_uas	(	pjsip_dialog *	dlg,
		const pjsip_evsub_user *	user_cb,
		pjsip_rx_data *	rdata,
		unsigned	option,
		pjsip_evsub **	p_evsub
	)

Create server subscription session.

Parameters

dlg	The underlying dialog to use.
user_cb	Callback to receive event subscription notifications.
rdata	The incoming request that creates the event subscription, such as SUBSCRIBE or REFER.
option	Bitmask of options.
p_evsub	Pointer to receive event subscription instance.

Returns

PJ_SUCCESS on success.

pjsip_evsub_terminate()

pj_status_t pjsip_evsub_terminate	(	pjsip_evsub *	sub,
		pj_bool_t	notify
	)

Forcefully destroy the subscription session. This function should only be called on special condition, such as when the subscription initialization has failed. For other conditions, application MUST terminate the subscription by sending the appropriate un(SUBSCRIBE) or NOTIFY.

Parameters

sub	The event subscription.
notify	Specify whether the state notification callback should be called.

Returns

PJ_SUCCESS if subscription session has been destroyed.

pjsip_evsub_get_state()

pjsip_evsub_state pjsip_evsub_get_state

(

const pjsip_evsub *

sub

)

Get subscription state.

Parameters

sub	Event subscription instance.

Returns

Subscription state.

pjsip_evsub_get_state_name()

const char * pjsip_evsub_get_state_name

(

const pjsip_evsub *

sub

)

Get the string representation of the subscription state.

Parameters

sub	Event subscription instance.

Returns

NULL terminated string.

pjsip_evsub_get_termination_reason()

const pj_str_t * pjsip_evsub_get_termination_reason

(

const pjsip_evsub *

sub

)

Get subscription termination reason, if any. If remote did not send termination reason, this function will return empty string.

Parameters

sub	Event subscription instance.

Returns

NULL terminated string.

pjsip_evsub_get_expires()

pj_uint32_t pjsip_evsub_get_expires

(

const pjsip_evsub *

sub

)

Get subscription expiration time.

Parameters

sub	Event subscription instance.

Returns

Subscription expiration time, in seconds.

pjsip_evsub_initiate()

pj_status_t pjsip_evsub_initiate	(	pjsip_evsub *	sub,
		const pjsip_method *	method,
		pj_uint32_t	expires,
		pjsip_tx_data **	p_tdata
	)

Call this function to create request to initiate subscription, to refresh subcription, or to request subscription termination.

Parameters

sub	Client subscription instance.
method	The method that establishes the subscription, such as SUBSCRIBE or REFER. If this argument is NULL, then SUBSCRIBE will be used.
expires	Subscription expiration. If the value is set to zero, this will request unsubscription. If the value is PJSIP_EXPIRES_NOT_SPECIFIED, default expiration as defined by the package will be used.
p_tdata	Pointer to receive the request.

Returns

PJ_SUCCESS on success.

pjsip_evsub_add_header()

pj_status_t pjsip_evsub_add_header	(	pjsip_evsub *	sub,
		const pjsip_hdr *	hdr_list
	)

Add a list of headers to the subscription instance. The list of headers will be added to outgoing presence subscription requests.

Parameters

sub	Subscription instance.
hdr_list	List of headers to be added.

Returns

PJ_SUCCESS on success.

pjsip_evsub_accept()

pj_status_t pjsip_evsub_accept	(	pjsip_evsub *	sub,
		pjsip_rx_data *	rdata,
		int	st_code,
		const pjsip_hdr *	hdr_list
	)

Accept the incoming subscription request by sending 2xx response to incoming SUBSCRIBE request.

Parameters

sub	Server subscription instance.
rdata	The incoming subscription request message.
st_code	Status code, which MUST be final response.
hdr_list	Optional list of headers to be added in the response.

Returns

PJ_SUCCESS on success.

pjsip_evsub_notify()

pj_status_t pjsip_evsub_notify	(	pjsip_evsub *	sub,
		pjsip_evsub_state	state,
		const pj_str_t *	state_str,
		const pj_str_t *	reason,
		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.
state_str	The state string name, if state contains value other than active, pending, or terminated. Otherwise this argument is ignored.
reason	Specify reason if new state is terminated, otherwise put NULL.
p_tdata	Pointer to receive request message.

Returns

PJ_SUCCESS on success.

pjsip_evsub_current_notify()

pj_status_t pjsip_evsub_current_notify	(	pjsip_evsub *	sub,
		pjsip_tx_data **	p_tdata
	)

For notifier, create a NOTIFY request that reflects current subscription status.

Parameters

sub	The server subscription instance.
p_tdata	Pointer to receive the request messge.

Returns

PJ_SUCCESS on success.

pjsip_evsub_send_request()

pj_status_t pjsip_evsub_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.

pjsip_tsx_get_evsub()

pjsip_evsub * pjsip_tsx_get_evsub

(

const pjsip_transaction *

tsx

)

Get the event subscription instance associated with the specified transaction.

Parameters

tsx	The transaction.

Returns

The event subscription instance registered in the transaction, if any.

pjsip_evsub_set_mod_data()

void pjsip_evsub_set_mod_data	(	pjsip_evsub *	sub,
		unsigned	mod_id,
		void *	data
	)

Set event subscription's module data.

Parameters

sub	The event subscription.
mod_id	The module id.
data	Arbitrary data.

pjsip_evsub_get_mod_data()

void * pjsip_evsub_get_mod_data	(	const pjsip_evsub *	sub,
		unsigned	mod_id
	)

Get event subscription's module data.

Parameters

sub	The event subscription.
mod_id	The module id.

Returns

Data previously set at the specified id.

pjsip_evsub_add_ref()

pj_status_t pjsip_evsub_add_ref

(

pjsip_evsub *

sub

)

Increment the event subscription's group lock.

Parameters

sub	The server subscription instance.

Returns

PJ_SUCCESS on success.

pjsip_evsub_dec_ref()

pj_status_t pjsip_evsub_dec_ref

(

pjsip_evsub *

sub

)

Decrement the event subscription's group lock.

Parameters

sub	The server subscription instance.

Returns

PJ_SUCCESS on success.

pjsip_evsub_uas_set_timeout()

void pjsip_evsub_uas_set_timeout	(	pjsip_evsub *	sub,
		pj_uint32_t	seconds
	)

Sets, resets, or cancels the UAS subscription timeout. If there is an existing timer, it is cancelled before any other action. A timeout of 0 is ignored except that any existing timer is cancelled.

The API is intended to be used to restore UAS' subscription timer from backup in the case of failure, and should not be used to modify an ongoing subscription's timeout.

Parameters

sub	The server subscription instance.
seconds	The new timeout.

References PJ_END_DECL.

Variable Documentation

pjsip_subscribe_method

const pjsip_method pjsip_subscribe_method

SUBSCRIBE method constant.

See also

pjsip_get_subscribe_method()

pjsip_notify_method

const pjsip_method pjsip_notify_method

NOTIFY method constant.

See also

pjsip_get_notify_method()