Group PJSIP_SIMPLE_PRES

group PJSIP_SIMPLE_PRES

Support for SIP Extension for Presence (RFC 3856)

This module contains the implementation of SIP Presence Extension as described in RFC 3856. It uses the SIP Event Notification framework (evsub.h) and extends the framework by implementing “presence” event package.

Defines

PJSIP_PRES_STATUS_MAX_INFO

Maximum presence status info.

Functions

pj_status_t pjsip_pres_init_module(pjsip_endpoint *endpt, pjsip_module *mod_evsub)

Initialize the presence 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_pres_instance(void)

Get the presence module instance.

Returns:

The presence module instance.

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

Create presence client subscription session.

Parameters:

  • dlg – The underlying dialog to use.

  • user_cb – Pointer to callbacks to receive presence subscription events.

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

  • p_evsub – Pointer to receive the presence subscription session.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_pres_create_uas(pjsip_dialog *dlg, const pjsip_evsub_user *user_cb, pjsip_rx_data *rdata, pjsip_evsub **p_evsub)

Create presence server subscription session.

Parameters:

  • dlg – The underlying dialog to use.

  • user_cb – Pointer to callbacks to receive presence subscription events.

  • rdata – The incoming SUBSCRIBE request that creates the event subscription.

  • p_evsub – Pointer to receive the presence subscription session.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_pres_terminate(pjsip_evsub *sub, pj_bool_t notify)

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

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

Returns:

PJ_SUCCESS if subscription session has been destroyed.

pj_status_t pjsip_pres_initiate(pjsip_evsub *sub, pj_uint32_t expires, pjsip_tx_data **p_tdata)

Call this function to create request to initiate presence 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. 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_pres_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_pres_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_pres_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. Application MUST set the presence status to the appropriate state (by calling pjsip_pres_set_status()) before calling this function.

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 the request.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_pres_current_notify(pjsip_evsub *sub, pjsip_tx_data **p_tdata)

Create NOTIFY request to reflect current subscription status.

Parameters:

  • sub – Server subscription object.

  • p_tdata – Pointer to receive request.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_pres_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 subscription object.

  • tdata – Request message to be sent.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_pres_get_status(pjsip_evsub *sub, pjsip_pres_status *status)

Get the presence 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 presence status.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_pres_set_status(pjsip_evsub *sub, const pjsip_pres_status *status)

Set the presence status. This operation is only valid for server subscription. After calling this function, application would need to send NOTIFY request to client.

Parameters:

  • sub – The server subscription.

  • status – Status to be set.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_pres_create_pidf(pj_pool_t *pool, const pjsip_pres_status *status, const pj_str_t *entity, pjsip_msg_body **p_body)

This is a utility function to create PIDF message body from PJSIP presence status (pjsip_pres_status).

Parameters:

  • pool – The pool to allocate memory for the message body.

  • status – Presence status to be converted into PIDF message body.

  • entity – The entity ID, which normally is equal to the presentity ID publishing this presence info.

  • p_body – Pointer to receive the SIP message body.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_pres_create_xpidf(pj_pool_t *pool, const pjsip_pres_status *status, const pj_str_t *entity, pjsip_msg_body **p_body)

This is a utility function to create X-PIDF message body from PJSIP presence status (pjsip_pres_status).

Parameters:

  • pool – The pool to allocate memory for the message body.

  • status – Presence status to be converted into X-PIDF message body.

  • entity – The entity ID, which normally is equal to the presentity ID publishing this presence info.

  • p_body – Pointer to receive the SIP message body.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_pres_parse_pidf(pjsip_rx_data *rdata, pj_pool_t *pool, pjsip_pres_status *status)

This is a utility function to parse PIDF body into PJSIP presence status.

See also

pjsip_pres_parse_pidf2()

Parameters:

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

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

  • status – The presence status to be initialized.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_pres_parse_pidf2(char *body, unsigned body_len, pj_pool_t *pool, pjsip_pres_status *status)

This is a utility function to parse PIDF body into PJSIP presence status.

See also

pjsip_pres_parse_pidf()

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 presence status structure.

  • status – The presence status to be initialized.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_pres_parse_xpidf(pjsip_rx_data *rdata, pj_pool_t *pool, pjsip_pres_status *status)

This is a utility function to parse X-PIDF body into PJSIP presence status.

See also

pjsip_pres_parse_xpidf2()

Parameters:

  • rdata – The incoming SIP message containing the X-PIDF body.

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

  • status – The presence status to be initialized.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_pres_parse_xpidf2(char *body, unsigned body_len, pj_pool_t *pool, pjsip_pres_status *status)

This is a utility function to parse X-PIDF body into PJSIP presence status.

See also

pjsip_pres_parse_xpidf()

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 presence status structure.

  • status – The presence status to be initialized.

Returns:

PJ_SUCCESS on success.

struct pjsip_pres_status
#include <presence.h>

This structure describes presence status of a presentity.

See also

pjsip_pres_status

Public Members

unsigned info_cnt

Number of info in the status.

pj_bool_t basic_open

Basic status/availability.

pjrpid_element rpid

Optional RPID info.

pj_str_t id

Tuple id.

pj_str_t contact

Optional contact address.

pj_xml_node *tuple_node

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

struct pjsip_pres_status::[anonymous] info[8]

Array of info.