res/pjproject/pjsip/include/pjsip-simple/publish.h

   1 /* $Id$ */
   2 /*
   3  * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
   4  * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  19  */
  20 #ifndef __PJSIP_SIMPLE_PUBLISH_H__
  21 #define __PJSIP_SIMPLE_PUBLISH_H__
  22
  23 /**
  24  * @file publish.h
  25  * @brief SIP Extension for Event State Publication (PUBLISH, RFC 3903)
  26  */
  27
  28 #include <pjsip/sip_util.h>
  29 #include <pjsip/sip_auth.h>
  30
  31
  32 PJ_BEGIN_DECL
  33
  34
  35 /**
  36  @defgroup PJSIP_SIMPLE_PUBLISH SIP Event State Publication (PUBLISH, RFC 3903)
  37  @ingroup PJSIP_SIMPLE
  38  @brief Support for SIP Event State Publication (PUBLISH, RFC 3903)
  39  @{
  40
  41  This module contains the implementation of Session Initiation Protocol (SIP)
  42  Extension for Event State Publication (PUBLISH) as defined by RFC 3903.
  43  */
  44
  45 /**
  46  * The SIP PUBLISH method constant.
  47  */
  48 extern const pjsip_method pjsip_publish_method;
  49
  50
  51 /*****************************************************************************
  52  * @defgroup PJSIP_SIMPLE_PUBLISH_CLIENT SIP Event State Publication Client
  53  * @ingroup PJSIP_SIMPLE
  54  * @brief Event State Publication Clien
  55  * @{
  56  */
  57
  58
  59 /** Expiration not specified. */
  60 #define PJSIP_PUBC_EXPIRATION_NOT_SPECIFIED     ((pj_uint32_t)0xFFFFFFFFUL)
  61
  62 /**
  63  * Opaque declaration for client side event publication session.
  64  */
  65 typedef struct pjsip_publishc pjsip_publishc;
  66
  67
  68 /**
  69  * Client publication options. Application should initialize this structure
  70  * with its default values by calling #pjsip_publishc_opt_default()
  71  */
  72 typedef struct pjsip_publishc_opt
  73 {
  74     /**
  75      * Specify whether the client publication session should queue the
  76      * PUBLISH request should there be another PUBLISH transaction still
  77      * pending. If this is set to false, the client will return error
  78      * on the PUBLISH request if there is another PUBLISH transaction still
  79      * in progress.
  80      *
  81      * Default: PJSIP_PUBLISHC_QUEUE_REQUEST
  82      */
  83     pj_bool_t   queue_request;
  84
  85 } pjsip_publishc_opt;
  86
  87
  88 /** Structure to hold parameters when calling application's callback.
  89  *  The application's callback is called when the client publication process
  90  *  has finished.
  91  */
  92 struct pjsip_publishc_cbparam
  93 {
  94     pjsip_publishc      *pubc;      /**< Client publication structure.      */
  95     void                *token;     /**< Arbitrary token.                   */
  96     pj_status_t          status;    /**< Error status.                      */
  97     int                  code;      /**< SIP status code received.          */
  98     pj_str_t             reason;    /**< SIP reason phrase received.        */
  99     pjsip_rx_data       *rdata;     /**< The complete received response.    */
 100     int                  expiration;/**< Next expiration interval. If the
 101                                          value is -1, it means the session
 102                                          will not renew itself.             */
 103 };
 104
 105
 106 /** Type declaration for callback to receive publication result. */
 107 typedef void pjsip_publishc_cb(struct pjsip_publishc_cbparam *param);
 108
 109
 110 /**
 111  * Initialize client publication session option with default values.
 112  *
 113  * @param opt       The option.
 114  */
 115 PJ_DECL(void) pjsip_publishc_opt_default(pjsip_publishc_opt *opt);
 116
 117
 118 /**
 119  * Initialize client publication module.
 120  *
 121  * @param endpt     SIP endpoint.
 122  *
 123  * @return          PJ_SUCCESS on success.
 124  */
 125 PJ_DECL(pj_status_t) pjsip_publishc_init_module(pjsip_endpoint *endpt);
 126
 127
 128 /**
 129  * Create client publication structure.
 130  *
 131  * @param endpt     Endpoint, used to allocate pool from.
 132  * @param opt       Options, or NULL to specify default options.
 133  * @param token     Opaque data to be associated with the client publication.
 134  * @param cb        Pointer to callback function to receive publication status.
 135  * @param p_pubc    Pointer to receive client publication structure.
 136  *
 137  * @return          PJ_SUCCESS on success.
 138  */
 139 PJ_DECL(pj_status_t) pjsip_publishc_create( pjsip_endpoint *endpt,
 140                                             const pjsip_publishc_opt *opt,
 141                                             void *token,
 142                                             pjsip_publishc_cb *cb,
 143                                             pjsip_publishc **p_pubc);
 144
 145
 146 /**
 147  * Destroy client publication structure. If a publication transaction is
 148  * in progress, then the structure will be deleted only after a final response
 149  * has been received, and in this case, the callback won't be called.
 150  *
 151  * @param pubc      The client publication structure.
 152  *
 153  * @return          PJ_SUCCESS on success.
 154  */
 155 PJ_DECL(pj_status_t) pjsip_publishc_destroy(pjsip_publishc *pubc);
 156
 157
 158
 159 /**
 160  * Get the memory pool associated with a publication client session.
 161  *
 162  * @param pubc      The client publication structure.
 163  * @return pool     handle.
 164  */
 165 PJ_DECL(pj_pool_t*) pjsip_publishc_get_pool(pjsip_publishc *pubc);
 166
 167
 168 /**
 169  * Initialize client publication structure with various information needed to
 170  * perform the publication.
 171  *
 172  * @param pubc          The client publication structure.
 173  * @param event         The Event identification (e.g. "presence").
 174  * @param target_uri    The URI of the presentity which the which the status
 175  *                      is being published.
 176  * @param from_uri      The URI of the endpoint who sends the event
 177  *                      publication. Normally the value would be the same as
 178  *                      target_uri.
 179  * @param to_uri        The URI to be put in To header. Normally the value
 180  *                      would be the same as target_uri.
 181  * @param expires       The default expiration of the event publication.
 182  *                      If the value PJSIP_PUBC_EXPIRATION_NOT_SPECIFIED is
 183  *                      given, then no default expiration will be applied.
 184  *
 185  * @return              PJ_SUCCESS on success.
 186  */
 187 PJ_DECL(pj_status_t) pjsip_publishc_init(pjsip_publishc *pubc,
 188                                          const pj_str_t *event,
 189                                          const pj_str_t *target_uri,
 190                                          const pj_str_t *from_uri,
 191                                          const pj_str_t *to_uri,
 192                                          pj_uint32_t expires);
 193
 194
 195 /**
 196  * Set authentication credentials to use by this publication.
 197  *
 198  * @param pubc      The publication structure.
 199  * @param count     Number of credentials in the array.
 200  * @param c         Array of credentials.
 201  *
 202  * @return          PJ_SUCCESS on success.
 203  */
 204 PJ_DECL(pj_status_t) pjsip_publishc_set_credentials(pjsip_publishc *pubc,
 205                                                     int count,
 206                                                     const pjsip_cred_info c[]);
 207
 208 /**
 209  * Set route set to be used for outgoing requests.
 210  *
 211  * @param pubc      The client publication structure.
 212  * @param rs        List containing Route headers.
 213  *
 214  * @return          PJ_SUCCESS on success.
 215  */
 216 PJ_DECL(pj_status_t) pjsip_publishc_set_route_set(pjsip_publishc *pubc,
 217                                                   const pjsip_route_hdr *rs);
 218
 219
 220 /**
 221  * Set list of headers to be added to each PUBLISH request generated by
 222  * the client publication session. Note that application can also add
 223  * the headers to the request after calling #pjsip_publishc_publish()
 224  * or #pjsip_publishc_unpublish(), but the benefit of this function is
 225  * the headers will also be added to requests generated internally by
 226  * the session, such as during session renewal/refresh.
 227  *
 228  * Note that calling this function will clear the previously added list
 229  * of headers.
 230  *
 231  * @param pubc      The client publication structure.
 232  * @param hdr_list  The list of headers.
 233  *
 234  * @return          PJ_SUCCESS on success.
 235  */
 236 PJ_DECL(pj_status_t) pjsip_publishc_set_headers(pjsip_publishc *pubc,
 237                                                 const pjsip_hdr *hdr_list);
 238
 239 /**
 240  * Create PUBLISH request for the specified client publication structure.
 241  * Application can use this function to both create initial publication
 242  * or to modify existing publication.
 243  *
 244  * After the PUBLISH request is created, application MUST fill in the
 245  * body part of the request with the appropriate content for the Event
 246  * being published.
 247  *
 248  * Note that publication refresh are handled automatically by the session
 249  * (as long as auto_refresh argument below is non-zero), and application
 250  * should not use this function to perform publication refresh.
 251  *
 252  * @param pubc          The client publication session.
 253  * @param auto_refresh  If non zero, the library will automatically
 254  *                      refresh the next publication until application
 255  *                      unpublish.
 256  * @param p_tdata       Pointer to receive the PUBLISH request. Note that
 257  *                      the request DOES NOT have a message body.
 258  *
 259  * @return              PJ_SUCCESS on success.
 260  */
 261 PJ_DECL(pj_status_t) pjsip_publishc_publish(pjsip_publishc *pubc,
 262                                              pj_bool_t auto_refresh,
 263                                              pjsip_tx_data **p_tdata);
 264
 265
 266 /**
 267  * Create PUBLISH request to unpublish the current client publication.
 268  *
 269  * @param pubc      The client publication structure.
 270  * @param p_tdata   Pointer to receive the PUBLISH request.
 271  *
 272  * @return          PJ_SUCCESS on success.
 273  */
 274 PJ_DECL(pj_status_t) pjsip_publishc_unpublish(pjsip_publishc *pubc,
 275                                               pjsip_tx_data **p_tdata);
 276
 277
 278 /**
 279  * Update the client publication expiration value. Note that this DOES NOT
 280  * automatically send outgoing PUBLISH request to update the publication
 281  * session. If application wants to do this, then it must construct a
 282  * PUBLISH request and send it to the server.
 283  *
 284  * @param pubc      The client publication structure.
 285  * @param expires   The new expires value.
 286  *
 287  * @return          PU_SUCCESS on successfull.
 288  */
 289 PJ_DECL(pj_status_t) pjsip_publishc_update_expires(pjsip_publishc *pubc,
 290                                                    pj_uint32_t expires );
 291
 292
 293 /**
 294  * Sends outgoing PUBLISH request. The process will complete asynchronously,
 295  * and application will be notified via the callback when the process
 296  * completes.
 297  *
 298  * If the session has another PUBLISH request outstanding, the behavior
 299  * depends on whether request queueing is enabled in the session (this was
 300  * set by setting \a queue_request field of #pjsip_publishc_opt to true
 301  * when calling #pjsip_publishc_create(). Default is true). If request
 302  * queueing is enabled, the request will be queued and the function will
 303  * return PJ_EPENDING. One the outstanding request is complete, the queued
 304  * request will be sent automatically. If request queueing is disabled, the
 305  * function will reject the request and return PJ_EBUSY.
 306  *
 307  * @param pubc      The client publication structure.
 308  * @param tdata     Transmit data.
 309  *
 310  * @return          - PJ_SUCCESS on success, or
 311  *                  - PJ_EPENDING if request is queued, or
 312  *                  - PJ_EBUSY if request is rejected because another PUBLISH
 313  *                    request is in progress, or
 314  *                  - other status code to indicate the error.
 315  */
 316 PJ_DECL(pj_status_t) pjsip_publishc_send(pjsip_publishc *pubc,
 317                                          pjsip_tx_data *tdata);
 318
 319
 320
 321 /**
 322  * @}
 323  */
 324
 325 /**
 326  * @}
 327  */
 328
 329 PJ_END_DECL
 330
 331
 332 #endif  /* __PJSIP_SIMPLE_PUBLISH_H__ */
 333