← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/pjsip/include/pjsip-simple/publish.h

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2015-01-07 14:51:16 UTC
  • mfrom: (4.3.5 sid)
  • Revision ID: package-import@ubuntu.com-20150107145116-yxnafinf4lrdvrmx
Tags: 1.4.1-0.1ubuntu1
* Merge with Debian, remaining changes:
 - Drop soprano, nepomuk build-dep
* Drop ubuntu patches, now upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/pjsip/include/pjsip-simple/publish.h
1
 
/* $Id: publish.h 4173 2012-06-20 10:39:05Z ming $ */
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
 
 * Set the "sent-by" field of the Via header for outgoing requests.
241
 
 *
242
 
 * @param pubc      The client publication structure.
243
 
 * @param via_addr  Set via_addr to use for the Via header or NULL to use
244
 
 *                  the transport's published name.
245
 
 * @param via_tp    via_addr will only be used if we are using via_tp
246
 
 *                  transport.
247
 
 *
248
 
 * @return          PJ_SUCCESS on success.
249
 
 */
250
 
PJ_DECL(pj_status_t) pjsip_publishc_set_via_sent_by(pjsip_publishc *pubc,
251
 
                                                    pjsip_host_port *via_addr,
252
 
                                                    pjsip_transport *via_tp);
253
 
 
254
 
 
255
 
/**
256
 
 * Create PUBLISH request for the specified client publication structure.
257
 
 * Application can use this function to both create initial publication
258
 
 * or to modify existing publication. 
259
 
 *
260
 
 * After the PUBLISH request is created, application MUST fill in the
261
 
 * body part of the request with the appropriate content for the Event
262
 
 * being published.
263
 
 *
264
 
 * Note that publication refresh are handled automatically by the session
265
 
 * (as long as auto_refresh argument below is non-zero), and application
266
 
 * should not use this function to perform publication refresh.
267
 
 *
268
 
 * @param pubc          The client publication session.
269
 
 * @param auto_refresh  If non zero, the library will automatically 
270
 
 *                      refresh the next publication until application 
271
 
 *                      unpublish.
272
 
 * @param p_tdata       Pointer to receive the PUBLISH request. Note that
273
 
 *                      the request DOES NOT have a message body.
274
 
 *
275
 
 * @return              PJ_SUCCESS on success.
276
 
 */
277
 
PJ_DECL(pj_status_t) pjsip_publishc_publish(pjsip_publishc *pubc, 
278
 
                                             pj_bool_t auto_refresh,
279
 
                                             pjsip_tx_data **p_tdata);
280
 
 
281
 
 
282
 
/**
283
 
 * Create PUBLISH request to unpublish the current client publication.
284
 
 *
285
 
 * @param pubc      The client publication structure.
286
 
 * @param p_tdata   Pointer to receive the PUBLISH request.
287
 
 *
288
 
 * @return          PJ_SUCCESS on success.
289
 
 */
290
 
PJ_DECL(pj_status_t) pjsip_publishc_unpublish(pjsip_publishc *pubc,
291
 
                                              pjsip_tx_data **p_tdata);
292
 
 
293
 
 
294
 
/**
295
 
 * Update the client publication expiration value. Note that this DOES NOT
296
 
 * automatically send outgoing PUBLISH request to update the publication
297
 
 * session. If application wants to do this, then it must construct a
298
 
 * PUBLISH request and send it to the server.
299
 
 *
300
 
 * @param pubc      The client publication structure.
301
 
 * @param expires   The new expires value.
302
 
 *
303
 
 * @return          PU_SUCCESS on successfull.
304
 
 */
305
 
PJ_DECL(pj_status_t) pjsip_publishc_update_expires(pjsip_publishc *pubc,
306
 
                                                   pj_uint32_t expires );
307
 
 
308
 
 
309
 
/**
310
 
 * Sends outgoing PUBLISH request. The process will complete asynchronously,
311
 
 * and application will be notified via the callback when the process 
312
 
 * completes.
313
 
 *
314
 
 * If the session has another PUBLISH request outstanding, the behavior
315
 
 * depends on whether request queueing is enabled in the session (this was
316
 
 * set by setting \a queue_request field of #pjsip_publishc_opt to true
317
 
 * when calling #pjsip_publishc_create(). Default is true). If request
318
 
 * queueing is enabled, the request will be queued and the function will 
319
 
 * return PJ_EPENDING. One the outstanding request is complete, the queued
320
 
 * request will be sent automatically. If request queueing is disabled, the
321
 
 * function will reject the request and return PJ_EBUSY.
322
 
 *
323
 
 * @param pubc      The client publication structure.
324
 
 * @param tdata     Transmit data.
325
 
 *
326
 
 * @return          - PJ_SUCCESS on success, or 
327
 
 *                  - PJ_EPENDING if request is queued, or
328
 
 *                  - PJ_EBUSY if request is rejected because another PUBLISH
329
 
 *                    request is in progress, or
330
 
 *                  - other status code to indicate the error.
331
 
 */
332
 
PJ_DECL(pj_status_t) pjsip_publishc_send(pjsip_publishc *pubc, 
333
 
                                         pjsip_tx_data *tdata);
334
 
 
335
 
 
336
 
 
337
 
/**
338
 
 * @}
339
 
 */
340
 
 
341
 
/**
342
 
 * @}
343
 
 */
344
 
 
345
 
PJ_END_DECL
346
 
 
347
 
 
348
 
#endif  /* __PJSIP_SIMPLE_PUBLISH_H__ */
349