diff options
Diffstat (limited to 'pjsip/include/pjsip-simple/publish.h')
-rw-r--r-- | pjsip/include/pjsip-simple/publish.h | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/pjsip/include/pjsip-simple/publish.h b/pjsip/include/pjsip-simple/publish.h new file mode 100644 index 00000000..141bbf6a --- /dev/null +++ b/pjsip/include/pjsip-simple/publish.h @@ -0,0 +1,252 @@ +/* $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 publish.h + * @brief SIP Extension for Event State Publication (PUBLISH, RFC 3903) + */ + + +PJ_BEGIN_DECL + + +/** + @defgroup PJSIP_SIMPLE_PUBLISH SIP Event State Publication (PUBLISH, RFC 3856) + @ingroup PJSIP_SIMPLE + @brief Support for SIP Event State Publication (PUBLISH, RFC 3856) + @{ + + This module contains the implementation of Session Initiation Protocol (SIP) + Extension for Event State Publication (PUBLISH) as defined by RFC 3856. + */ + + +/***************************************************************************** + * @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); + + + +/** + * Create client publication structure. + * + * @param endpt Endpoint, used to allocate pool from. + * @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, + 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_PRESENCE_H__ */ + |