/* $Id$ */ /* * Copyright (C) 2008-2009 Teluu Inc. (http://www.teluu.com) * Copyright (C) 2003-2008 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_PUBLISH_H__ #define __PJSIP_SIMPLE_PUBLISH_H__ /** * @file publish.h * @brief SIP Extension for Event State Publication (PUBLISH, RFC 3903) */ #include #include PJ_BEGIN_DECL /** @defgroup PJSIP_SIMPLE_PUBLISH SIP Event State Publication (PUBLISH, RFC 3903) @ingroup PJSIP_SIMPLE @brief Support for SIP Event State Publication (PUBLISH, RFC 3903) @{ This module contains the implementation of Session Initiation Protocol (SIP) Extension for Event State Publication (PUBLISH) as defined by RFC 3903. */ /** * The SIP PUBLISH method constant. */ extern const pjsip_method pjsip_publish_method; /***************************************************************************** * @defgroup PJSIP_SIMPLE_PUBLISH_CLIENT SIP Event State Publication Client * @ingroup PJSIP_SIMPLE * @brief Event State Publication Clien * @{ */ /** Expiration not specified. */ #define PJSIP_PUBC_EXPIRATION_NOT_SPECIFIED ((pj_uint32_t)0xFFFFFFFFUL) /** * Opaque declaration for client side event publication session. */ typedef struct pjsip_publishc pjsip_publishc; /** Structure to hold parameters when calling application's callback. * The application's callback is called when the client publication process * has finished. */ struct pjsip_publishc_cbparam { pjsip_publishc *pubc; /**< Client publication structure. */ void *token; /**< Arbitrary token. */ pj_status_t status; /**< Error status. */ int code; /**< SIP status code received. */ pj_str_t reason; /**< SIP reason phrase received. */ pjsip_rx_data *rdata; /**< The complete received response. */ int expiration;/**< Next expiration interval. */ }; /** Type declaration for callback to receive publication result. */ typedef void pjsip_publishc_cb(struct pjsip_publishc_cbparam *param); /** * Initialize client publication module. * * @param endpt SIP endpoint. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_publishc_init_module(pjsip_endpoint *endpt); /** * Create client publication structure. * * @param endpt Endpoint, used to allocate pool from. * @param options Option flags. * @param token Opaque data to be associated with the client publication. * @param cb Pointer to callback function to receive publication status. * @param p_pubc Pointer to receive client publication structure. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_publishc_create( pjsip_endpoint *endpt, unsigned options, void *token, pjsip_publishc_cb *cb, pjsip_publishc **p_pubc); /** * Destroy client publication structure. If a publication transaction is * in progress, then the structure will be deleted only after a final response * has been received, and in this case, the callback won't be called. * * @param pubc The client publication structure. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_publishc_destroy(pjsip_publishc *pubc); /** * Get the memory pool associated with a publication client session. * * @param pubc The client publication structure. * @return pool handle. */ PJ_DECL(pj_pool_t*) pjsip_publishc_get_pool(pjsip_publishc *pubc); /** * Initialize client publication structure with various information needed to * perform the publication. * * @param pubc The client publication structure. * @param event The Event identification (e.g. "presence"). * @param target_uri The URI of the presentity which the which the status * is being published. * @param from_uri The URI of the endpoint who sends the event * publication. Normally the value would be the same as * target_uri. * @param to_uri The URI to be put in To header. Normally the value * would be the same as target_uri. * @param expires The default expiration of the event publication. * If the value PJSIP_PUBC_EXPIRATION_NOT_SPECIFIED is * given, then no default expiration will be applied. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_publishc_init(pjsip_publishc *pubc, const pj_str_t *event, const pj_str_t *target_uri, const pj_str_t *from_uri, const pj_str_t *to_uri, pj_uint32_t expires); /** * Set authentication credentials to use by this publication. * * @param pubc The publication structure. * @param count Number of credentials in the array. * @param c Array of credentials. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_publishc_set_credentials(pjsip_publishc *pubc, int count, const pjsip_cred_info c[]); /** * Set route set to be used for outgoing requests. * * @param pubc The client publication structure. * @param rs List containing Route headers. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_publishc_set_route_set(pjsip_publishc *pubc, const pjsip_route_hdr *rs); /** * Create PUBLISH request for the specified client publication structure. * Application can use this function to both create initial publication * or to modify existing publication. * * After the PUBLISH request is created, application MUST fill in the * body part of the request with the appropriate content for the Event * being published. * * Note that publication refresh are handled automatically by the session * (as long as auto_refresh argument below is non-zero), and application * should not use this function to perform publication refresh. * * @param pubc The client publication session. * @param auto_refresh If non zero, the library will automatically * refresh the next publication until application * unpublish. * @param p_tdata Pointer to receive the PUBLISH request. Note that * the request DOES NOT have a message body. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_publishc_publish(pjsip_publishc *pubc, pj_bool_t auto_refresh, pjsip_tx_data **p_tdata); /** * Create PUBLISH request to unpublish the current client publication. * * @param pubc The client publication structure. * @param p_tdata Pointer to receive the PUBLISH request. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_publishc_unpublish(pjsip_publishc *pubc, pjsip_tx_data **p_tdata); /** * Update the client publication expiration value. Note that this DOES NOT * automatically send outgoing PUBLISH request to update the publication * session. If application wants to do this, then it must construct a * PUBLISH request and send it to the server. * * @param pubc The client publication structure. * @param expires The new expires value. * * @return PU_SUCCESS on successfull. */ PJ_DECL(pj_status_t) pjsip_publishc_update_expires(pjsip_publishc *pubc, pj_uint32_t expires ); /** * Sends outgoing PUBLISH request. The process will complete asynchronously, * and application will be notified via the callback when the process * completes. * * @param pubc The client publication structure. * @param tdata Transmit data. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_publishc_send(pjsip_publishc *pubc, pjsip_tx_data *tdata); /** * @} */ /** * @} */ PJ_END_DECL #endif /* __PJSIP_SIMPLE_PUBLISH_H__ */