diff options
author | Benny Prijono <bennylp@teluu.com> | 2005-11-09 16:27:11 +0000 |
---|---|---|
committer | Benny Prijono <bennylp@teluu.com> | 2005-11-09 16:27:11 +0000 |
commit | 9f379fcbe89024353a25b3737d79ec7a82b6408f (patch) | |
tree | b6ce94ad1d8af3ffdf4fa82fe659d50d9ece34db /pjsip/include/pjsip-simple/presence.h | |
parent | d578e2e00a14e5faa775c51a25ddbc2f3d3a2fda (diff) |
Begin organizing directory structure of pjsip
git-svn-id: http://svn.pjsip.org/repos/pjproject/main@38 74dad513-b988-da41-8d7b-12977e46ad98
Diffstat (limited to 'pjsip/include/pjsip-simple/presence.h')
-rw-r--r-- | pjsip/include/pjsip-simple/presence.h | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/pjsip/include/pjsip-simple/presence.h b/pjsip/include/pjsip-simple/presence.h new file mode 100644 index 00000000..80ed93c0 --- /dev/null +++ b/pjsip/include/pjsip-simple/presence.h @@ -0,0 +1,214 @@ +/* $Id$ + * + */ +#ifndef __PJSIP_SIMPLE_PRESENCE_H__ +#define __PJSIP_SIMPLE_PRESENCE_H__ + +/** + * @file presence.h + * @brief SIP Extension for Presence (RFC 3856) + */ +#include <pjsip_simple/event_notify.h> +#include <pjsip_simple/pidf.h> +#include <pjsip_simple/xpidf.h> + + +PJ_BEGIN_DECL + + +/** + * @defgroup PJSIP_SIMPLE_PRES SIP Extension for Presence (RFC 3856) + * @ingroup PJSIP_SIMPLE + * @{ + * + * This module contains the implementation of SIP Presence Extension as + * described in RFC 3856. It uses the SIP Event Notification framework + * (event_notify.h) and extends the framework by implementing "presence" + * event package. + */ + +/** + * Presence message body type. + */ +typedef enum pjsip_pres_type +{ + PJSIP_PRES_TYPE_PIDF, + PJSIP_PRES_TYPE_XPIDF, +} pjsip_pres_type; + +/** + * This structure describe a presentity, for both subscriber and notifier. + */ +typedef struct pjsip_presentity +{ + pjsip_event_sub *sub; /**< Event subscribtion record. */ + pjsip_pres_type pres_type; /**< Presentity type. */ + pjsip_msg_body *uas_body; /**< Message body (UAS only). */ + union { + pjpidf_pres *pidf; + pjxpidf_pres *xpidf; + } uas_data; /**< UAS data. */ + pj_str_t timestamp; /**< Time of last update. */ + void *user_data; /**< Application data. */ +} pjsip_presentity; + + +/** + * This structure describe callback that is registered to receive notification + * from the presence module. + */ +typedef struct pjsip_presence_cb +{ + /** + * This callback is first called when the module receives incoming + * SUBSCRIBE request to determine whether application wants to accept + * the request. If it does, then on_presence_request will be called. + * + * @param rdata The received message. + * @return Application should return 2xx to accept the request, + * or failure status (>=300) to reject the request. + */ + void (*accept_presence)(pjsip_rx_data *rdata, int *status); + + /** + * This callback is called when the module receive the first presence + * subscription request. + * + * @param pres The presence descriptor. + * @param rdata The incoming request. + * @param timeout Timeout to be set for incoming request. Otherwise + * app can just leave this and accept the default. + */ + void (*on_received_request)(pjsip_presentity *pres, pjsip_rx_data *rdata, + int *timeout); + + /** + * This callback is called when the module received subscription refresh + * request. + * + * @param pres The presence descriptor. + * @param rdata The incoming request. + */ + void (*on_received_refresh)(pjsip_presentity *pres, pjsip_rx_data *rdata); + + /** + * This callback is called when the module receives incoming NOTIFY + * request. + * + * @param pres The presence descriptor. + * @param open The latest status of the presentity. + */ + void (*on_received_update)(pjsip_presentity *pres, pj_bool_t open); + + /** + * This callback is called when the subscription has terminated. + * + * @param sub The subscription instance. + * @param reason The termination reason. + */ + void (*on_terminated)(pjsip_presentity *pres, const pj_str_t *reason); + +} pjsip_presence_cb; + + +/** + * Initialize the presence module and register callback. + * + * @param cb Callback structure. + */ +PJ_DECL(void) pjsip_presence_init(const pjsip_presence_cb *cb); + + +/** + * Create to presence subscription of a presentity URL. + * + * @param endpt Endpoint instance. + * @param local_url Local URL. + * @param remote_url Remote URL which the presence is being subscribed. + * @param expires The expiration. + * @param user_data User data to attach to presence subscription. + * + * @return The presence structure if successfull, or NULL if + * failed. + */ +PJ_DECL(pjsip_presentity*) pjsip_presence_create( pjsip_endpoint *endpt, + const pj_str_t *local_url, + const pj_str_t *remote_url, + int expires, + void *user_data ); + +/** + * Set credentials to be used by this presentity for outgoing requests. + * + * @param pres Presentity instance. + * @param count Number of credentials in the array. + * @param cred Array of credentials. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_presence_set_credentials( pjsip_presentity *pres, + int count, + const pjsip_cred_info cred[]); + +/** + * Set route set for outgoing requests. + * + * @param pres Presentity instance. + * @param route_set List of route headers. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_presence_set_route_set( pjsip_presentity *pres, + const pjsip_route_hdr *hdr ); + +/** + * Send SUBSCRIBE request for the specified presentity. + * + * @param pres The presentity instance. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_presence_subscribe( pjsip_presentity *pres ); + +/** + * Ceased the presence subscription. + * + * @param pres The presence structure. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_presence_unsubscribe( pjsip_presentity *pres ); + +/** + * Notify subscriber about change in local status. + * + * @param pres The presence structure. + * @param state Set the state of the subscription. + * @param open Set the presence status (open or closed). + * + * @return Zero if a NOTIFY request can be sent. + */ +PJ_DECL(pj_status_t) pjsip_presence_notify( pjsip_presentity *pres, + pjsip_event_sub_state state, + pj_bool_t open ); + +/** + * Destroy presence structure and the underlying subscription. + * + * @param pres The presence structure. + * + * @return Zero if the subscription was destroyed, or one if + * the subscription can not be destroyed immediately + * and will be destroyed later, or -1 if failed. + */ +PJ_DECL(pj_status_t) pjsip_presence_destroy( pjsip_presentity *pres ); + + +/** + * @} + */ + +PJ_END_DECL + + +#endif /* __PJSIP_SIMPLE_PRESENCE_H__ */ |