/* $Id$ */ /* * Copyright (C) 2003-2006 Benny Prijono * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program 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 General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; 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 #include #include #include /** * @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__ */