Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / 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