Group PJSIP_EVENT_NOT

group PJSIP_EVENT_NOT

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

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

Typedefs

typedefPJ_BEGIN_DECL struct pjsip_evsub pjsip_evsub

Opaque type for event subscription session.

typedef enum pjsip_evsub_state pjsip_evsub_state

See

pjsip_evsub_state

Enums

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.

Values:

enumerator PJSIP_EVSUB_STATE_NULL

State is NULL.

enumerator PJSIP_EVSUB_STATE_SENT

Client has sent SUBSCRIBE request.

enumerator PJSIP_EVSUB_STATE_ACCEPTED

2xx response to SUBSCRIBE has been sent/received.

enumerator PJSIP_EVSUB_STATE_PENDING

Subscription is pending.

enumerator PJSIP_EVSUB_STATE_ACTIVE

Subscription is active.

enumerator PJSIP_EVSUB_STATE_TERMINATED

Subscription is terminated.

enumerator PJSIP_EVSUB_STATE_UNKNOWN

Subscription state can not be determined. Application can query the state by calling pjsip_evsub_get_state_name().

enum [anonymous]

Some options for the event subscription.

Values:

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.

Functions

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

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.

  • 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

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

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.

Variables

const pjsip_method pjsip_subscribe_method

SUBSCRIBE method constant.

See

pjsip_get_subscribe_method()

const pjsip_method pjsip_notify_method

NOTIFY method constant.

See

pjsip_get_notify_method()

struct pjsip_evsub_user
#include <evsub.h>

This structure describes callback that is registered by application or package to receive notifications about subscription events.

See

pjsip_evsub_user