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().
-
enumerator PJSIP_EVSUB_STATE_NULL
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
-
const pjsip_method pjsip_notify_method
NOTIFY method constant.
See also
-
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
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.
-
void (*on_evsub_state)(pjsip_evsub *sub, pjsip_event *event)
-
typedef struct pjsip_evsub pjsip_evsub