Group PJSIP_SIMPLE_DLG_EVENT

group PJSIP_SIMPLE_DLG_EVENT

Support for SIP Extension for Dialog Event (RFC 4235)

This module contains the implementation of INVITE-Initiated Dialog Event Package as described in RFC 4235. It uses the SIP Event Notification framework (evsub.h) and extends the framework by implementing “dialog-info+xml” event package. This could be useful for features such as Busy Lamp Field (BLF).

Defines

PJSIP_DLG_EVENT_STATUS_MAX_INFO

Maximum dialog event status info items which can handled by application.

Functions

pj_status_t pjsip_dlg_event_init_module(pjsip_endpoint *endpt, pjsip_module *mod_evsub)

Initialize the dialog event 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_bdlg_event_instance(void)

Get the dialog event module instance.

Returns:

The dialog event module instance.

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

Create dialog event client subscription session.

Parameters:

  • dlg – The underlying dialog to use.

  • user_cb – Pointer to callbacks to receive dialog events.

  • options – Option flags. Currently only PJSIP_EVSUB_NO_EVENT_ID is recognized.

  • p_evsub – Pointer to receive the dialog event subscription session.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_dlg_event_terminate(pjsip_evsub *sub, pj_bool_t notify)

Forcefully destroy the dialog event 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 dialog event subscription.

  • notify – Specify whether the state notification callback should be called.

Returns:

PJ_SUCCESS if subscription session has been destroyed.

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

Call this function to create request to initiate dialog event 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_dlg_event_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 dialog event subscription requests.

Parameters:

  • sub – Subscription instance.

  • hdr_list – List of headers to be added.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_dlg_event_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_dlg_event_send_request(pjsip_evsub *sub, pjsip_tx_data *tdata)

Send request message. 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.

pj_status_t pjsip_dlg_event_get_status(pjsip_evsub *sub, pjsip_dlg_event_status *status)

Get the dialog event status. Client normally would call this function after receiving NOTIFY request from server.

Parameters:

  • sub – The client or server subscription.

  • status – The structure to receive dialog event status.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_dlg_event_parse_dialog_info(pjsip_rx_data *rdata, pj_pool_t *pool, pjsip_dlg_event_status *dlg_status)

This is a utility function to parse XML body into PJSIP dialog event status.

See also

pjsip_dlg_event_parse_dialog_info()

Parameters:

  • rdata – The incoming SIP message containing the XML body.

  • pool – Pool to allocate memory to copy the strings into the dialog event status structure.

  • status – The dialog event status to be initialized.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_dlg_event_parse_dialog_info2(char *body, unsigned body_len, pj_pool_t *pool, pjsip_dlg_event_status *dlg_status)

This is a utility function to parse XML body into PJSIP dialog event status.

See also

pjsip_dlg_event_parse_dialog_info2()

Parameters:

  • body – Text body, with one extra space at the end to place NULL character temporarily during parsing.

  • body_len – Length of the body, not including the NULL termination character.

  • pool – Pool to allocate memory to copy the strings into the dialog event status structure.

  • status – The dialog event status to be initialized.

Returns:

PJ_SUCCESS on success.

struct pjsip_dlg_event_status
#include <dlg_event.h>

This structure describes dialog event status of an entity.

See also

pjsip_dlg_event_status

Public Members

unsigned info_cnt

Number of info in the status

pj_str_t dialog_info_state

Dialog-Info state

pj_str_t dialog_info_entity

Dialog-Info entity

pj_str_t dialog_call_id

Dialog’s call_id

pj_str_t dialog_remote_tag

Dialog’s remote-tag

pj_str_t dialog_local_tag

Dialog’s local-tag

pj_str_t dialog_direction

Dialog’s direction

pj_str_t dialog_id

Dialog’s id

pj_str_t dialog_state

Dialog state

pj_str_t dialog_duration

Dialog duration

pj_xml_node *dialog_node

Pointer to tuple XML node of parsed dialog-info body received from remote agent. Only valid for client subscription. If the last received NOTIFY request does not contain any dialog-info body, this will be set to NULL

struct pjsip_dlg_event_status::[anonymous] info[8]

Array of info.