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

typedef struct pjsip_evsub pjsip_evsub

Opaque type for event subscription session.

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. The value must not be greater than PJSIP_GENERIC_ARRAY_MAX_COUNT.

  • accept – Array of Accept value.

Returns:

PJ_SUCCESS on success.

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.

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

Get subscription state.

Parameters:

sub – Event subscription instance.

Returns:

Subscription state.

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.

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.

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.

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.

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

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

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.

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.

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.

Variables

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

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 also

pjsip_evsub_user

Public Members

void (*on_evsub_state)(pjsip_evsub *sub, pjsip_event *event)

This callback is called when subscription state has changed. Application MUST be prepared to receive NULL event and events with type other than PJSIP_EVENT_TSX_STATE

This callback is OPTIONAL.

Param sub:

The subscription instance.

Param event:

The event that has caused the state to change, which may be NULL or may have type other than PJSIP_EVENT_TSX_STATE.

void (*on_tsx_state)(pjsip_evsub *sub, pjsip_transaction *tsx, pjsip_event *event)

This callback is called when transaction state has changed.

Param sub:

The subscription instance.

Param tsx:

Transaction.

Param event:

The event.

void (*on_rx_refresh)(pjsip_evsub *sub, pjsip_rx_data *rdata, int *p_st_code, pj_str_t **p_st_text, pjsip_hdr *res_hdr, pjsip_msg_body **p_body)

This callback is called when incoming SUBSCRIBE (or any method that establishes the subscription in the first place) is received. It allows application to specify what response should be sent to remote, along with additional headers and message body to be put in the response.

This callback is only applicable and required for UAS.

Upon receiving this callback, implementation MUST send NOTIFY request. The suggested behavior is to call pjsip_evsub_current_notify(), since this function takes care about unsubscription request and calculates the appropriate expiration interval.

Param sub:

The subscription instance.

Param rdata:

The received SUBSCRIBE request.

Param p_st_code:

Application MUST set the value of this argument with final status code (200-699) upon returning from the callback. Only applicable for refresh request. For unsubscription, the library will always reply with 200.

Param p_st_text:

Custom status text, if any.

Param res_hdr:

Upon return, application can put additional headers to be sent in the response in this list.

Param p_body:

Application MAY specify message body to be sent in the response.

void (*on_rx_notify)(pjsip_evsub *sub, pjsip_rx_data *rdata, int *p_st_code, pj_str_t **p_st_text, pjsip_hdr *res_hdr, pjsip_msg_body **p_body)

This callback is called when client/subscriber received incoming NOTIFY request. It allows the application to specify what response should be sent to remote, along with additional headers and message body to be put in the response.

This callback is OPTIONAL. When it is not implemented, the default behavior is to respond incoming NOTIFY request with 200 (OK).

Param sub:

The subscription instance.

Param rdata:

The received NOTIFY request.

Param p_st_code:

Application MUST set the value of this argument with final status code (200-699) upon returning from the callback.

Param p_st_text:

Custom status text, if any.

Param res_hdr:

Upon return, application can put additional headers to be sent in the response in this list.

Param p_body:

Application MAY specify message body to be sent in the response.

void (*on_client_refresh)(pjsip_evsub *sub)

This callback is called when it is time for the client to refresh the subscription.

This callback is OPTIONAL when PJSIP package such as presence or refer is used; the event package will refresh subscription by sending SUBSCRIBE with the interval set to current/last interval.

Param sub:

The subscription instance.

void (*on_server_timeout)(pjsip_evsub *sub)

This callback is called when server doesn’t receive subscription refresh after the specified subscription interval.

This callback is OPTIONAL when PJSIP package such as presence or refer is used; the event package send NOTIFY to terminate the subscription.