Added initial PUBLISH client support, and also default account selection in pjsua/pjsua-lib
git-svn-id: https://svn.pjsip.org/repos/pjproject/trunk@683 74dad513-b988-da41-8d7b-12977e46ad98
diff --git a/pjsip/include/pjsip-simple/publish.h b/pjsip/include/pjsip-simple/publish.h
new file mode 100644
index 0000000..141bbf6
--- /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__ */
+