BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJSIP Reference

SIP Extension for Presence (RFC 3856)

Support for SIP Extension for Presence (RFC 3856) More...

Data Structures

struct  pjsip_pres_status
 

Macros

#define PJSIP_PRES_STATUS_MAX_INFO   8
 

Functions

pj_status_t pjsip_pres_init_module (pjsip_endpoint *endpt, pjsip_module *mod_evsub)
 
pjsip_modulepjsip_pres_instance (void)
 
pj_status_t pjsip_pres_create_uac (pjsip_dialog *dlg, const pjsip_evsub_user *user_cb, unsigned options, pjsip_evsub **p_evsub)
 
pj_status_t pjsip_pres_create_uas (pjsip_dialog *dlg, const pjsip_evsub_user *user_cb, pjsip_rx_data *rdata, pjsip_evsub **p_evsub)
 
pj_status_t pjsip_pres_terminate (pjsip_evsub *sub, pj_bool_t notify)
 
pj_status_t pjsip_pres_initiate (pjsip_evsub *sub, pj_int32_t expires, pjsip_tx_data **p_tdata)
 
pj_status_t pjsip_pres_add_header (pjsip_evsub *sub, const pjsip_hdr *hdr_list)
 
pj_status_t pjsip_pres_accept (pjsip_evsub *sub, pjsip_rx_data *rdata, int st_code, const pjsip_hdr *hdr_list)
 
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)
 
pj_status_t pjsip_pres_current_notify (pjsip_evsub *sub, pjsip_tx_data **p_tdata)
 
pj_status_t pjsip_pres_send_request (pjsip_evsub *sub, pjsip_tx_data *tdata)
 
pj_status_t pjsip_pres_get_status (pjsip_evsub *sub, pjsip_pres_status *status)
 
pj_status_t pjsip_pres_set_status (pjsip_evsub *sub, const pjsip_pres_status *status)
 
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)
 
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)
 
pj_status_t pjsip_pres_parse_pidf (pjsip_rx_data *rdata, pj_pool_t *pool, pjsip_pres_status *status)
 
pj_status_t pjsip_pres_parse_pidf2 (char *body, unsigned body_len, pj_pool_t *pool, pjsip_pres_status *status)
 
pj_status_t pjsip_pres_parse_xpidf (pjsip_rx_data *rdata, pj_pool_t *pool, pjsip_pres_status *status)
 
pj_status_t pjsip_pres_parse_xpidf2 (char *body, unsigned body_len, pj_pool_t *pool, pjsip_pres_status *status)
 

Detailed Description

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.

Macro Definition Documentation

#define PJSIP_PRES_STATUS_MAX_INFO   8

Maximum presence status info.

Function Documentation

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
endptThe endpoint instance.
mod_evsubThe 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
dlgThe underlying dialog to use.
user_cbPointer to callbacks to receive presence subscription events.
optionsOption flags. Currently only PJSIP_EVSUB_NO_EVENT_ID is recognized.
p_evsubPointer 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
dlgThe underlying dialog to use.
user_cbPointer to callbacks to receive presence subscription events.
rdataThe incoming SUBSCRIBE request that creates the event subscription.
p_evsubPointer 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
subThe presence subscription.
notifySpecify 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_int32_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
subClient subscription instance.
expiresSubscription expiration. If the value is set to zero, this will request unsubscription.
p_tdataPointer 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
subSubscription instance.
hdr_listList 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
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.
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
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 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
subServer subscription object.
p_tdataPointer 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
subThe subscription object.
tdataRequest 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
subThe client or server subscription.
statusThe 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
subThe server subscription.
statusStatus 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
poolThe pool to allocate memory for the message body.
statusPresence status to be converted into PIDF message body.
entityThe entity ID, which normally is equal to the presentity ID publishing this presence info.
p_bodyPointer 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
poolThe pool to allocate memory for the message body.
statusPresence status to be converted into X-PIDF message body.
entityThe entity ID, which normally is equal to the presentity ID publishing this presence info.
p_bodyPointer 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.

Parameters
rdataThe incoming SIP message containing the PIDF body.
poolPool to allocate memory to copy the strings into the presence status structure.
statusThe presence status to be initialized.
Returns
PJ_SUCCESS on success.
See also
pjsip_pres_parse_pidf2()
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.

Parameters
bodyText body, with one extra space at the end to place NULL character temporarily during parsing.
body_lenLength of the body, not including the NULL termination character.
poolPool to allocate memory to copy the strings into the presence status structure.
statusThe presence status to be initialized.
Returns
PJ_SUCCESS on success.
See also
pjsip_pres_parse_pidf()
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.

Parameters
rdataThe incoming SIP message containing the X-PIDF body.
poolPool to allocate memory to copy the strings into the presence status structure.
statusThe presence status to be initialized.
Returns
PJ_SUCCESS on success.
See also
pjsip_pres_parse_xpidf2()
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.

Parameters
bodyText body, with one extra space at the end to place NULL character temporarily during parsing.
body_lenLength of the body, not including the NULL termination character.
poolPool to allocate memory to copy the strings into the presence status structure.
statusThe presence status to be initialized.
Returns
PJ_SUCCESS on success.
See also
pjsip_pres_parse_xpidf()

 


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