SIP Event Notification (RFC 3265) Module
[Event and Presence Framework]

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

typedef typedefPJ_BEGIN_DECL struct pjsip_evsub pjsip_evsub

Opaque type for event subscription session.

typedef enum pjsip_evsub_state pjsip_evsub_state

See also:: pjsip_evsub_state

typedef struct pjsip_evsub_user pjsip_evsub_user

See also:: pjsip_evsub_user

Enumeration Type Documentation

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

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

const pjsip_method* pjsip_get_subscribe_method ( void )

SUBSCRIBE method constant.

const pjsip_method* pjsip_get_notify_method ( void )

NOTIFY method constant.

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_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.

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[]
	)

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.
	accept	Array of Accept value.

Returns:: PJ_SUCCESS on success.

const pjsip_hdr* pjsip_evsub_get_allow_events_hdr ( pjsip_module * m )

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

Parameters:

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

Returns:: The Allow-Events header.

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.

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.

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_state pjsip_evsub_get_state ( pjsip_evsub * sub )

Get subscription state.

Parameters:

sub

Event subscription instance.

Returns:: Subscription state.

const char* pjsip_evsub_get_state_name ( pjsip_evsub * sub )

Get the string representation of the subscription state.

Parameters:

sub

Event subscription instance.

Returns:: NULL terminated string.

const pj_str_t* pjsip_evsub_get_termination_reason ( 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.

pj_status_t pjsip_evsub_initiate	(	pjsip_evsub *	sub,
		const pjsip_method *	method,
		pj_int32_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 negative, default expiration as defined by the package will be used.
	p_tdata	Pointer to receive the request.

Returns:: PJ_SUCCESS on success.

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.

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.

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.

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_evsub* pjsip_tsx_get_evsub ( 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.

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.

void* pjsip_evsub_get_mod_data	(	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.

Variable Documentation

const pjsip_method pjsip_subscribe_method

SUBSCRIBE method constant.

See also:: pjsip_get_subscribe_method()

const pjsip_method pjsip_notify_method

NOTIFY method constant.

See also:: pjsip_get_notify_method()

SIP Event Notification (RFC 3265) Module [Event and Presence Framework]

Detailed Description

Modules

Data Structures

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation

SIP Event Notification (RFC 3265) Module
[Event and Presence Framework]