diff options
Diffstat (limited to 'pjsip/include/pjsip-simple/event_notify.h')
-rw-r--r-- | pjsip/include/pjsip-simple/event_notify.h | 652 |
1 files changed, 337 insertions, 315 deletions
diff --git a/pjsip/include/pjsip-simple/event_notify.h b/pjsip/include/pjsip-simple/event_notify.h index 91b53657..6cfee4e5 100644 --- a/pjsip/include/pjsip-simple/event_notify.h +++ b/pjsip/include/pjsip-simple/event_notify.h @@ -1,315 +1,337 @@ -/* $Id$ - * - */ -#ifndef __PJSIP_SIMPLE_EVENT_NOTIFY_H__ -#define __PJSIP_SIMPLE_EVENT_NOTIFY_H__ - -/** - * @file event_notify.h - * @brief SIP Specific Event Notification Extension (RFC 3265) - */ - -#include <pjsip/sip_types.h> -#include <pjsip/sip_auth.h> -#include <pjsip_simple/event_notify_msg.h> -#include <pj/timer.h> - -/** - * @defgroup PJSIP_EVENT_NOT SIP Event Notification (RFC 3265) Module - * @ingroup PJSIP_SIMPLE - * @{ - * - * 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). - */ - -PJ_BEGIN_DECL - -typedef struct pjsip_event_sub_cb pjsip_event_sub_cb; -typedef struct pjsip_event_sub pjsip_event_sub; - -/** - * This enumeration describes 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_EVENT_SUB_STATE_UNKNOWN, and the token will be kept in state_str - * member of the susbcription structure. - */ -typedef enum pjsip_event_sub_state -{ - /** State is NULL. */ - PJSIP_EVENT_SUB_STATE_NULL, - - /** Subscription is active. */ - PJSIP_EVENT_SUB_STATE_ACTIVE, - - /** Subscription is pending. */ - PJSIP_EVENT_SUB_STATE_PENDING, - - /** Subscription is terminated. */ - PJSIP_EVENT_SUB_STATE_TERMINATED, - - /** Subscription state can not be determined. Application can query - * the state information in state_str member. - */ - PJSIP_EVENT_SUB_STATE_UNKNOWN, - -} pjsip_event_sub_state; - -/** - * This structure describes notification to be called when incoming SUBSCRIBE - * request is received. The module will call the callback registered by package - * that matches the event description in the incoming SUBSCRIBE. - */ -typedef struct pjsip_event_sub_pkg_cb -{ - /** - * This callback is called to first enquery the package whether it wants - * to accept incoming SUBSCRIBE request. If it does, then on_subscribe - * will be called. - * - * @param rdata The incoming request. - * @param status The status code to be returned back to subscriber. - */ - void (*on_query_subscribe)(pjsip_rx_data *rdata, int *status); - - /** - * This callback is called when the module receives incoming SUBSCRIBE - * request. - * - * @param sub The subscription instance. - * @param rdata The received buffer. - * @param cb Callback to be registered to the subscription instance. - * @param expires The expiration to be set. - */ - void (*on_subscribe)(pjsip_event_sub *sub, pjsip_rx_data *rdata, - pjsip_event_sub_cb **cb, int *expires); - -} pjsip_event_sub_pkg_cb; - -/** - * This structure describes callback that is registered by application or - * package to receive notifications about a subscription. - */ -struct pjsip_event_sub_cb -{ - /** - * This callback is used by both subscriber and notifier. It is called - * when the subscription has been terminated. - * - * @param sub The subscription instance. - * @param reason The termination reason. - */ - void (*on_sub_terminated)(pjsip_event_sub *sub, const pj_str_t *reason); - - /** - * This callback is called when we received SUBSCRIBE request to refresh - * the subscription. - * - * @param sub The subscription instance. - * @param rdata The received SUBSCRIBE request. - */ - void (*on_received_refresh)(pjsip_event_sub *sub, pjsip_rx_data *rdata); - - /** - * This callback is called when the module receives final response on - * previously sent SUBSCRIBE request. - * - * @param sub The subscription instance. - * @param event The event. - */ - void (*on_received_sub_response)(pjsip_event_sub *sub, pjsip_event *event); - - /** - * This callback is called when the module receives incoming NOTIFY - * request. - * - * @param sub The subscription instance. - * @param rdata The received data. - */ - void (*on_received_notify)(pjsip_event_sub *sub, pjsip_rx_data *rdata); - - /** - * This callback is called when the module receives final response to - * previously sent NOTIFY request. - * - * @param sub The subscription instance. - * @param event The event. - */ - void (*on_received_notify_response)(pjsip_event_sub *sub, pjsip_event *event); - -}; - -/** - * This structure describes an event subscription record. The structure is used - * to represent both subscriber and notifier. - */ -struct pjsip_event_sub -{ - pj_pool_t *pool; /**< Pool. */ - pjsip_endpoint *endpt; /**< Endpoint. */ - pjsip_event_sub_cb cb; /**< Callback. */ - pj_mutex_t *mutex; /**< Mutex. */ - pjsip_role_e role; /**< Role (UAC=subscriber, UAS=notifier) */ - pjsip_event_sub_state state; /**< Subscription state. */ - pj_str_t state_str; /**< String describing the state. */ - pjsip_from_hdr *from; /**< Cached local info (From) */ - pjsip_to_hdr *to; /**< Cached remote info (To) */ - pjsip_contact_hdr *contact; /**< Cached local contact. */ - pjsip_cid_hdr *call_id; /**< Cached Call-ID */ - int cseq; /**< Outgoing CSeq */ - pjsip_event_hdr *event; /**< Event description. */ - pjsip_expires_hdr *uac_expires; /**< Cached Expires header (UAC only). */ - pjsip_accept_hdr *local_accept; /**< Local Accept header. */ - pjsip_route_hdr route_set; /**< Route-set. */ - - pj_str_t key; /**< Key in the hash table. */ - void *user_data; /**< Application data. */ - int default_interval; /**< Refresh interval. */ - pj_timer_entry timer; /**< Internal timer. */ - pj_time_val expiry_time; /**< Time when subscription expires. */ - int pending_tsx; /**< Number of pending transactions. */ - pj_bool_t delete_flag; /**< Pending deletion flag. */ - - pjsip_auth_session auth_sess; /**< Authorization sessions. */ - unsigned cred_cnt; /**< Number of credentials. */ - pjsip_cred_info *cred_info; /**< Array of credentials. */ -}; - - - - -/** - * Initialize the module and get the instance of the module to be registered to - * endpoint. - * - * @return The module instance. - */ -PJ_DECL(pjsip_module*) pjsip_event_sub_get_module(void); - - -/** - * Register event package. - * - * @param event The event identification for the package. - * @param accept_cnt Number of strings in Accept array. - * @param accept Array of Accept value. - * @param cb Callback to receive incoming SUBSCRIBE for the package. - * - * @return Zero on success. - */ -PJ_DECL(pj_status_t) pjsip_event_sub_register_pkg( const pj_str_t *event_name, - int accept_cnt, - const pj_str_t accept[], - const pjsip_event_sub_pkg_cb *cb ); - - -/** - * Create initial subscription instance (client). - * - * @param endpt The endpoint. - * @param from URL to put in From header. - * @param to The target resource. - * @param event Event package. - * @param expires Expiration time. - * @param accept Accept specification. - * @param user_data Application data to attach to this subscription. - * - * @return New client subscription instance. - */ -PJ_DECL(pjsip_event_sub*) pjsip_event_sub_create( pjsip_endpoint *endpt, - const pj_str_t *from, - const pj_str_t *to, - const pj_str_t *event, - int expires, - int accept_cnt, - const pj_str_t accept[], - void *user_data, - const pjsip_event_sub_cb *cb); - -/** - * Set credentials to be used for outgoing request messages. - * - * @param sub Subscription instance. - * @param count Number of credentials. - * @param cred Array of credential info. - * - * @return Zero on success. - */ -PJ_DECL(pj_status_t) pjsip_event_sub_set_credentials( pjsip_event_sub *sub, - int count, - const pjsip_cred_info cred[]); - -/** - * Set route set for outgoing requests. - * - * @param sub Subscription instance. - * @param route_set List of route headers. - * - * @return Zero on success. - */ -PJ_DECL(pj_status_t) pjsip_event_sub_set_route_set( pjsip_event_sub *sub, - const pjsip_route_hdr *route_set ); - - -/** - * Send SUBSCRIBE request. - * - * @param sub Subscription instance. - * - * @return Zero on success. - */ -PJ_DECL(pj_status_t) pjsip_event_sub_subscribe( pjsip_event_sub *sub ); - -/** - * Terminate subscription (client). This will send unsubscription request to - * notifier. - * - * @param sub Client subscription instance. - * - * @return Zero on success. - */ -PJ_DECL(pj_status_t) pjsip_event_sub_unsubscribe( pjsip_event_sub *sub ); - - -/** - * For notifier, send NOTIFY request to subscriber, and set the state of - * the subscription. - * - * @param sub The server subscription (notifier) instance. - * @param state New state to set. - * @param reason Specify reason if new state is terminated, otherwise - * put NULL. - * @param type Description of content type. - * @param body Text body to send with the NOTIFY, or NULL if the - * NOTIFY request should not contain any message body. - * - * @return Zero on success. - */ -PJ_DECL(pj_status_t) pjsip_event_sub_notify( pjsip_event_sub *sub, - pjsip_event_sub_state state, - const pj_str_t *reason, - pjsip_msg_body *body); - -/** - * Destroy subscription instance. - * - * @param sub The client or server subscription instance. - * - * @return Zero on success, one if the subscription will be - * deleted automatically later, or -1 on error. - */ -PJ_DECL(pj_status_t) pjsip_event_sub_destroy(pjsip_event_sub *sub); - - -PJ_END_DECL - -/** - * @} - */ - -#endif /* __PJSIP_SIMPLE_EVENT_NOTIFY_H__ */ +/* $Id$
+ *
+ */
+/*
+ * PJSIP - SIP Stack
+ * (C)2003-2005 Benny Prijono <bennylp@bulukucing.org>
+ *
+ * Author:
+ * Benny Prijono <bennylp@bulukucing.org>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ *
+ */
+#ifndef __PJSIP_SIMPLE_EVENT_NOTIFY_H__
+#define __PJSIP_SIMPLE_EVENT_NOTIFY_H__
+
+/**
+ * @file event_notify.h
+ * @brief SIP Specific Event Notification Extension (RFC 3265)
+ */
+
+#include <pjsip/sip_types.h>
+#include <pjsip/sip_auth.h>
+#include <pjsip_simple/event_notify_msg.h>
+#include <pj/timer.h>
+
+/**
+ * @defgroup PJSIP_EVENT_NOT SIP Event Notification (RFC 3265) Module
+ * @ingroup PJSIP_SIMPLE
+ * @{
+ *
+ * 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).
+ */
+
+PJ_BEGIN_DECL
+
+typedef struct pjsip_event_sub_cb pjsip_event_sub_cb;
+typedef struct pjsip_event_sub pjsip_event_sub;
+
+/**
+ * This enumeration describes 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_EVENT_SUB_STATE_UNKNOWN, and the token will be kept in state_str
+ * member of the susbcription structure.
+ */
+typedef enum pjsip_event_sub_state
+{
+ /** State is NULL. */
+ PJSIP_EVENT_SUB_STATE_NULL,
+
+ /** Subscription is active. */
+ PJSIP_EVENT_SUB_STATE_ACTIVE,
+
+ /** Subscription is pending. */
+ PJSIP_EVENT_SUB_STATE_PENDING,
+
+ /** Subscription is terminated. */
+ PJSIP_EVENT_SUB_STATE_TERMINATED,
+
+ /** Subscription state can not be determined. Application can query
+ * the state information in state_str member.
+ */
+ PJSIP_EVENT_SUB_STATE_UNKNOWN,
+
+} pjsip_event_sub_state;
+
+/**
+ * This structure describes notification to be called when incoming SUBSCRIBE
+ * request is received. The module will call the callback registered by package
+ * that matches the event description in the incoming SUBSCRIBE.
+ */
+typedef struct pjsip_event_sub_pkg_cb
+{
+ /**
+ * This callback is called to first enquery the package whether it wants
+ * to accept incoming SUBSCRIBE request. If it does, then on_subscribe
+ * will be called.
+ *
+ * @param rdata The incoming request.
+ * @param status The status code to be returned back to subscriber.
+ */
+ void (*on_query_subscribe)(pjsip_rx_data *rdata, int *status);
+
+ /**
+ * This callback is called when the module receives incoming SUBSCRIBE
+ * request.
+ *
+ * @param sub The subscription instance.
+ * @param rdata The received buffer.
+ * @param cb Callback to be registered to the subscription instance.
+ * @param expires The expiration to be set.
+ */
+ void (*on_subscribe)(pjsip_event_sub *sub, pjsip_rx_data *rdata,
+ pjsip_event_sub_cb **cb, int *expires);
+
+} pjsip_event_sub_pkg_cb;
+
+/**
+ * This structure describes callback that is registered by application or
+ * package to receive notifications about a subscription.
+ */
+struct pjsip_event_sub_cb
+{
+ /**
+ * This callback is used by both subscriber and notifier. It is called
+ * when the subscription has been terminated.
+ *
+ * @param sub The subscription instance.
+ * @param reason The termination reason.
+ */
+ void (*on_sub_terminated)(pjsip_event_sub *sub, const pj_str_t *reason);
+
+ /**
+ * This callback is called when we received SUBSCRIBE request to refresh
+ * the subscription.
+ *
+ * @param sub The subscription instance.
+ * @param rdata The received SUBSCRIBE request.
+ */
+ void (*on_received_refresh)(pjsip_event_sub *sub, pjsip_rx_data *rdata);
+
+ /**
+ * This callback is called when the module receives final response on
+ * previously sent SUBSCRIBE request.
+ *
+ * @param sub The subscription instance.
+ * @param event The event.
+ */
+ void (*on_received_sub_response)(pjsip_event_sub *sub, pjsip_event *event);
+
+ /**
+ * This callback is called when the module receives incoming NOTIFY
+ * request.
+ *
+ * @param sub The subscription instance.
+ * @param rdata The received data.
+ */
+ void (*on_received_notify)(pjsip_event_sub *sub, pjsip_rx_data *rdata);
+
+ /**
+ * This callback is called when the module receives final response to
+ * previously sent NOTIFY request.
+ *
+ * @param sub The subscription instance.
+ * @param event The event.
+ */
+ void (*on_received_notify_response)(pjsip_event_sub *sub, pjsip_event *event);
+
+};
+
+/**
+ * This structure describes an event subscription record. The structure is used
+ * to represent both subscriber and notifier.
+ */
+struct pjsip_event_sub
+{
+ pj_pool_t *pool; /**< Pool. */
+ pjsip_endpoint *endpt; /**< Endpoint. */
+ pjsip_event_sub_cb cb; /**< Callback. */
+ pj_mutex_t *mutex; /**< Mutex. */
+ pjsip_role_e role; /**< Role (UAC=subscriber, UAS=notifier) */
+ pjsip_event_sub_state state; /**< Subscription state. */
+ pj_str_t state_str; /**< String describing the state. */
+ pjsip_from_hdr *from; /**< Cached local info (From) */
+ pjsip_to_hdr *to; /**< Cached remote info (To) */
+ pjsip_contact_hdr *contact; /**< Cached local contact. */
+ pjsip_cid_hdr *call_id; /**< Cached Call-ID */
+ int cseq; /**< Outgoing CSeq */
+ pjsip_event_hdr *event; /**< Event description. */
+ pjsip_expires_hdr *uac_expires; /**< Cached Expires header (UAC only). */
+ pjsip_accept_hdr *local_accept; /**< Local Accept header. */
+ pjsip_route_hdr route_set; /**< Route-set. */
+
+ pj_str_t key; /**< Key in the hash table. */
+ void *user_data; /**< Application data. */
+ int default_interval; /**< Refresh interval. */
+ pj_timer_entry timer; /**< Internal timer. */
+ pj_time_val expiry_time; /**< Time when subscription expires. */
+ int pending_tsx; /**< Number of pending transactions. */
+ pj_bool_t delete_flag; /**< Pending deletion flag. */
+
+ pjsip_auth_session auth_sess; /**< Authorization sessions. */
+ unsigned cred_cnt; /**< Number of credentials. */
+ pjsip_cred_info *cred_info; /**< Array of credentials. */
+};
+
+
+
+
+/**
+ * Initialize the module and get the instance of the module to be registered to
+ * endpoint.
+ *
+ * @return The module instance.
+ */
+PJ_DECL(pjsip_module*) pjsip_event_sub_get_module(void);
+
+
+/**
+ * Register event package.
+ *
+ * @param event The event identification for the package.
+ * @param accept_cnt Number of strings in Accept array.
+ * @param accept Array of Accept value.
+ * @param cb Callback to receive incoming SUBSCRIBE for the package.
+ *
+ * @return Zero on success.
+ */
+PJ_DECL(pj_status_t) pjsip_event_sub_register_pkg( const pj_str_t *event_name,
+ int accept_cnt,
+ const pj_str_t accept[],
+ const pjsip_event_sub_pkg_cb *cb );
+
+
+/**
+ * Create initial subscription instance (client).
+ *
+ * @param endpt The endpoint.
+ * @param from URL to put in From header.
+ * @param to The target resource.
+ * @param event Event package.
+ * @param expires Expiration time.
+ * @param accept Accept specification.
+ * @param user_data Application data to attach to this subscription.
+ *
+ * @return New client subscription instance.
+ */
+PJ_DECL(pjsip_event_sub*) pjsip_event_sub_create( pjsip_endpoint *endpt,
+ const pj_str_t *from,
+ const pj_str_t *to,
+ const pj_str_t *event,
+ int expires,
+ int accept_cnt,
+ const pj_str_t accept[],
+ void *user_data,
+ const pjsip_event_sub_cb *cb);
+
+/**
+ * Set credentials to be used for outgoing request messages.
+ *
+ * @param sub Subscription instance.
+ * @param count Number of credentials.
+ * @param cred Array of credential info.
+ *
+ * @return Zero on success.
+ */
+PJ_DECL(pj_status_t) pjsip_event_sub_set_credentials( pjsip_event_sub *sub,
+ int count,
+ const pjsip_cred_info cred[]);
+
+/**
+ * Set route set for outgoing requests.
+ *
+ * @param sub Subscription instance.
+ * @param route_set List of route headers.
+ *
+ * @return Zero on success.
+ */
+PJ_DECL(pj_status_t) pjsip_event_sub_set_route_set( pjsip_event_sub *sub,
+ const pjsip_route_hdr *route_set );
+
+
+/**
+ * Send SUBSCRIBE request.
+ *
+ * @param sub Subscription instance.
+ *
+ * @return Zero on success.
+ */
+PJ_DECL(pj_status_t) pjsip_event_sub_subscribe( pjsip_event_sub *sub );
+
+/**
+ * Terminate subscription (client). This will send unsubscription request to
+ * notifier.
+ *
+ * @param sub Client subscription instance.
+ *
+ * @return Zero on success.
+ */
+PJ_DECL(pj_status_t) pjsip_event_sub_unsubscribe( pjsip_event_sub *sub );
+
+
+/**
+ * For notifier, send NOTIFY request to subscriber, and set the state of
+ * the subscription.
+ *
+ * @param sub The server subscription (notifier) instance.
+ * @param state New state to set.
+ * @param reason Specify reason if new state is terminated, otherwise
+ * put NULL.
+ * @param type Description of content type.
+ * @param body Text body to send with the NOTIFY, or NULL if the
+ * NOTIFY request should not contain any message body.
+ *
+ * @return Zero on success.
+ */
+PJ_DECL(pj_status_t) pjsip_event_sub_notify( pjsip_event_sub *sub,
+ pjsip_event_sub_state state,
+ const pj_str_t *reason,
+ pjsip_msg_body *body);
+
+/**
+ * Destroy subscription instance.
+ *
+ * @param sub The client or server subscription instance.
+ *
+ * @return Zero on success, one if the subscription will be
+ * deleted automatically later, or -1 on error.
+ */
+PJ_DECL(pj_status_t) pjsip_event_sub_destroy(pjsip_event_sub *sub);
+
+
+PJ_END_DECL
+
+/**
+ * @}
+ */
+
+#endif /* __PJSIP_SIMPLE_EVENT_NOTIFY_H__ */
|