BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJSIP Reference

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

Modules

 Additional Header Fields
 

Data Structures

struct  pjsip_evsub_user
 

Typedefs

typedef typedefPJ_BEGIN_DECL 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_methodpjsip_get_subscribe_method (void)
 
const pjsip_methodpjsip_get_notify_method (void)
 
pj_status_t pjsip_evsub_init_module (pjsip_endpoint *endpt)
 
pjsip_modulepjsip_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_hdrpjsip_evsub_get_allow_events_hdr (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 (pjsip_evsub *sub)
 
const char * pjsip_evsub_get_state_name (pjsip_evsub *sub)
 
const pj_str_tpjsip_evsub_get_termination_reason (pjsip_evsub *sub)
 
pj_status_t pjsip_evsub_initiate (pjsip_evsub *sub, const pjsip_method *method, pj_int32_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_evsubpjsip_tsx_get_evsub (pjsip_transaction *tsx)
 
void pjsip_evsub_set_mod_data (pjsip_evsub *sub, unsigned mod_id, void *data)
 
void * pjsip_evsub_get_mod_data (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 typedefPJ_BEGIN_DECL struct pjsip_evsub pjsip_evsub

Opaque type for event subscription session.

Enumeration Type Documentation

◆ 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
endptThe 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_modThe module that implements the event package being registered.
event_nameEvent package identification.
expiresDefault subscription expiration time, in seconds.
accept_cntNumber of strings in Accept array. The value must not be greater than PJSIP_GENERIC_ARRAY_MAX_COUNT.
acceptArray of Accept value.
Returns
PJ_SUCCESS on success.

◆ pjsip_evsub_get_allow_events_hdr()

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
mPointer 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
dlgThe underlying dialog to use.
user_cbCallback to receive event subscription notifications.
eventEvent name.
optionBitmask of options.
p_evsubPointer 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
dlgThe underlying dialog to use.
user_cbCallback to receive event subscription notifications.
rdataThe incoming request that creates the event subscription, such as SUBSCRIBE or REFER.
optionBitmask of options.
p_evsubPointer 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
subThe event subscription.
notifySpecify 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 ( pjsip_evsub sub)

Get subscription state.

Parameters
subEvent subscription instance.
Returns
Subscription state.

◆ pjsip_evsub_get_state_name()

const char* pjsip_evsub_get_state_name ( pjsip_evsub sub)

Get the string representation of the subscription state.

Parameters
subEvent subscription instance.
Returns
NULL terminated string.

◆ pjsip_evsub_get_termination_reason()

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
subEvent subscription instance.
Returns
NULL terminated string.

◆ pjsip_evsub_initiate()

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
subClient subscription instance.
methodThe method that establishes the subscription, such as SUBSCRIBE or REFER. If this argument is NULL, then SUBSCRIBE will be used.
expiresSubscription 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_tdataPointer 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
subSubscription instance.
hdr_listList 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
subServer subscription instance.
rdataThe incoming subscription request message.
st_codeStatus code, which MUST be final response.
hdr_listOptional 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
subThe server subscription (notifier) instance.
stateNew state to set.
state_strThe state string name, if state contains value other than active, pending, or terminated. Otherwise this argument is ignored.
reasonSpecify reason if new state is terminated, otherwise put NULL.
p_tdataPointer 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
subThe server subscription instance.
p_tdataPointer 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
subThe event subscription object.
tdataRequest message to be send.
Returns
PJ_SUCCESS on success.

◆ pjsip_tsx_get_evsub()

pjsip_evsub* pjsip_tsx_get_evsub ( pjsip_transaction tsx)

Get the event subscription instance associated with the specified transaction.

Parameters
tsxThe 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
subThe event subscription.
mod_idThe module id.
dataArbitrary data.

◆ pjsip_evsub_get_mod_data()

void* pjsip_evsub_get_mod_data ( pjsip_evsub sub,
unsigned  mod_id 
)

Get event subscription's module data.

Parameters
subThe event subscription.
mod_idThe 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
subThe 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
subThe 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.

Parameters
subThe server subscription instance.
secondsThe new timeout.

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

 


PJSIP Open Source, high performance, small footprint, and very very portable SIP stack
Copyright (C) 2006-2008 Teluu Inc.