SIP Message Summary and Message Waiting Indication (RFC 3842)
[Event and Presence Framework]

Support for SIP MWI Extension (RFC 3842). More...

Functions
pj_status_t	pjsip_mwi_init_module (pjsip_endpoint *endpt, pjsip_module *mod_evsub)
pjsip_module *	pjsip_mwi_instance (void)
pj_status_t	pjsip_mwi_create_uac (pjsip_dialog *dlg, const pjsip_evsub_user *user_cb, unsigned options, pjsip_evsub **p_evsub)
pj_status_t	pjsip_mwi_create_uas (pjsip_dialog *dlg, const pjsip_evsub_user *user_cb, pjsip_rx_data *rdata, pjsip_evsub **p_evsub)
pj_status_t	pjsip_mwi_terminate (pjsip_evsub *sub, pj_bool_t notify)
pj_status_t	pjsip_mwi_initiate (pjsip_evsub *sub, pj_int32_t expires, pjsip_tx_data **p_tdata)
pj_status_t	pjsip_mwi_accept (pjsip_evsub *sub, pjsip_rx_data *rdata, int st_code, const pjsip_hdr *hdr_list)
pj_status_t	pjsip_mwi_notify (pjsip_evsub *sub, pjsip_evsub_state state, const pj_str_t *state_str, const pj_str_t *reason, const pjsip_media_type *mime_type, const pj_str_t *body, pjsip_tx_data **p_tdata)
pj_status_t	pjsip_mwi_current_notify (pjsip_evsub *sub, pjsip_tx_data **p_tdata)
pj_status_t	pjsip_mwi_send_request (pjsip_evsub *sub, pjsip_tx_data *tdata)

---

Detailed Description

This module implements RFC 3842: A Message Summary and Message Waiting Indication Event Package for the Session Initiation Protocol (SIP). It uses the SIP Event Notification framework (evsub.h) and extends the framework by implementing "message-summary" event package.

---

Function Documentation

pj_status_t pjsip_mwi_init_module	(	pjsip_endpoint *	endpt,
		pjsip_module *	mod_evsub
	)

Initialize the MWI module and register it as endpoint module and package to the event subscription module.

Parameters:

	endpt	The endpoint instance.
	mod_evsub	The event subscription module instance.

Returns:

PJ_SUCCESS if the module is successfully initialized and registered to both endpoint and the event subscription module.

pjsip_module* pjsip_mwi_instance

(

void

)

Get the MWI module instance.

Returns:

The MWI module instance.

pj_status_t pjsip_mwi_create_uac	(	pjsip_dialog *	dlg,
		const pjsip_evsub_user *	user_cb,
		unsigned	options,
		pjsip_evsub **	p_evsub
	)

Create MWI client subscription session.

Parameters:

	dlg	The underlying dialog to use.
	user_cb	Pointer to callbacks to receive MWI subscription events.
	options	Option flags. Currently only PJSIP_EVSUB_NO_EVENT_ID is recognized.
	p_evsub	Pointer to receive the MWI subscription session.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_mwi_create_uas	(	pjsip_dialog *	dlg,
		const pjsip_evsub_user *	user_cb,
		pjsip_rx_data *	rdata,
		pjsip_evsub **	p_evsub
	)

Create MWI server subscription session.

Parameters:

	dlg	The underlying dialog to use.
	user_cb	Pointer to callbacks to receive MWI subscription events.
	rdata	The incoming SUBSCRIBE request that creates the event subscription.
	p_evsub	Pointer to receive the MWI subscription session.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_mwi_terminate	(	pjsip_evsub *	sub,
		pj_bool_t	notify
	)

Forcefully destroy the MWI subscription. 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 MWI subscription.
	notify	Specify whether the state notification callback should be called.

Returns:

PJ_SUCCESS if subscription session has been destroyed.

pj_status_t pjsip_mwi_initiate	(	pjsip_evsub *	sub,
		pj_int32_t	expires,
		pjsip_tx_data **	p_tdata
	)

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

Parameters:

	sub	Client subscription instance.
	expires	Subscription expiration. If the value is set to zero, this will request unsubscription.
	p_tdata	Pointer to receive the request.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_mwi_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_mwi_notify	(	pjsip_evsub *	sub,
		pjsip_evsub_state	state,
		const pj_str_t *	state_str,
		const pj_str_t *	reason,
		const pjsip_media_type *	mime_type,
		const pj_str_t *	body,
		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.
	mime_type	MIME type/content type of the message body.
	body	Message body to be included in the NOTIFY request.
	p_tdata	Pointer to receive the request.

Returns:

PJ_SUCCESS on success.

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

Create NOTIFY request containing message body from the last NOITFY message created.

Parameters:

	sub	Server subscription object.
	p_tdata	Pointer to receive request.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_mwi_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 subscription object.
	tdata	Request message to be sent.

Returns:

PJ_SUCCESS on success.