pjsip/include/pjsip-simple/presence.h

/* $Id$ */
/* 
 * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
 *
 * 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_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__ */