pjsip/src/pjsip_simple/event_notify.h

/* $Header: /pjproject/pjsip/src/pjsip_simple/event_notify.h 7     8/31/05 9:05p Bennylp $ */
#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__ */