← Back to branch summary

~ubuntu-branches/ubuntu/vivid/sflphone/vivid

« back to all changes in this revision

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

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2013-06-30 11:40:56 UTC
  • mfrom: (4.1.18 saucy-proposed)
  • Revision ID: package-import@ubuntu.com-20130630114056-0np50jkyqo6vnmii
Tags: 1.2.3-2
* changeset_r92d62cfc54732bbbcfff2b1d36c096b120b981a5.diff 
  - fixes automatic endian detection 
* Update Vcs: fixes vcs-field-not-canonical

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject/pjsip/include/pjsip-simple/presence.h
1
 
/* $Id: presence.h 3553 2011-05-05 06:14:19Z nanang $ */
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_PRESENCE_H__
21
 
#define __PJSIP_SIMPLE_PRESENCE_H__
22
 
 
23
 
/**
24
 
 * @file presence.h
25
 
 * @brief SIP Extension for Presence (RFC 3856)
26
 
 */
27
 
#include <pjsip-simple/evsub.h>
28
 
#include <pjsip-simple/pidf.h>
29
 
#include <pjsip-simple/xpidf.h>
30
 
#include <pjsip-simple/rpid.h>
31
 
 
32
 
 
33
 
PJ_BEGIN_DECL
34
 
 
35
 
 
36
 
/**
37
 
 * @defgroup PJSIP_SIMPLE_PRES SIP Extension for Presence (RFC 3856)
38
 
 * @ingroup PJSIP_SIMPLE
39
 
 * @brief Support for SIP Extension for Presence (RFC 3856)
40
 
 * @{
41
 
 *
42
 
 * This module contains the implementation of SIP Presence Extension as 
43
 
 * described in RFC 3856. It uses the SIP Event Notification framework
44
 
 * (evsub.h) and extends the framework by implementing "presence"
45
 
 * event package.
46
 
 */
47
 
 
48
 
 
49
 
 
50
 
/**
51
 
 * Initialize the presence module and register it as endpoint module and
52
 
 * package to the event subscription module.
53
 
 *
54
 
 * @param endpt         The endpoint instance.
55
 
 * @param mod_evsub     The event subscription module instance.
56
 
 *
57
 
 * @return              PJ_SUCCESS if the module is successfully 
58
 
 *                      initialized and registered to both endpoint
59
 
 *                      and the event subscription module.
60
 
 */
61
 
PJ_DECL(pj_status_t) pjsip_pres_init_module(pjsip_endpoint *endpt,
62
 
                                            pjsip_module *mod_evsub);
63
 
 
64
 
 
65
 
/**
66
 
 * Get the presence module instance.
67
 
 *
68
 
 * @return              The presence module instance.
69
 
 */
70
 
PJ_DECL(pjsip_module*) pjsip_pres_instance(void);
71
 
 
72
 
 
73
 
/**
74
 
 * Maximum presence status info.
75
 
 */
76
 
#define PJSIP_PRES_STATUS_MAX_INFO  8
77
 
 
78
 
 
79
 
/**
80
 
 * This structure describes presence status of a presentity.
81
 
 */
82
 
struct pjsip_pres_status
83
 
{
84
 
    unsigned            info_cnt;       /**< Number of info in the status.  */
85
 
    struct {
86
 
 
87
 
        pj_bool_t       basic_open;     /**< Basic status/availability.     */
88
 
        pjrpid_element  rpid;           /**< Optional RPID info.            */
89
 
 
90
 
        pj_str_t        id;             /**< Tuple id.                      */
91
 
        pj_str_t        contact;        /**< Optional contact address.      */
92
 
 
93
 
        pj_xml_node    *tuple_node;     /**< Pointer to tuple XML node of
94
 
                                             parsed PIDF body received from
95
 
                                             remote agent. Only valid for
96
 
                                             client subscription. If the
97
 
                                             last received NOTIFY request
98
 
                                             does not contain any PIDF body,
99
 
                                             this valud will be set to NULL */
100
 
 
101
 
    } info[PJSIP_PRES_STATUS_MAX_INFO]; /**< Array of info.                 */
102
 
 
103
 
    pj_bool_t           _is_valid;      /**< Internal flag.                 */
104
 
};
105
 
 
106
 
 
107
 
/**
108
 
 * @see pjsip_pres_status
109
 
 */
110
 
typedef struct pjsip_pres_status pjsip_pres_status;
111
 
 
112
 
 
113
 
/**
114
 
 * Create presence client subscription session.
115
 
 *
116
 
 * @param dlg           The underlying dialog to use.
117
 
 * @param user_cb       Pointer to callbacks to receive presence subscription
118
 
 *                      events.
119
 
 * @param options       Option flags. Currently only PJSIP_EVSUB_NO_EVENT_ID
120
 
 *                      is recognized.
121
 
 * @param p_evsub       Pointer to receive the presence subscription
122
 
 *                      session.
123
 
 *
124
 
 * @return              PJ_SUCCESS on success.
125
 
 */
126
 
PJ_DECL(pj_status_t) pjsip_pres_create_uac( pjsip_dialog *dlg,
127
 
                                            const pjsip_evsub_user *user_cb,
128
 
                                            unsigned options,
129
 
                                            pjsip_evsub **p_evsub );
130
 
 
131
 
 
132
 
/**
133
 
 * Create presence server subscription session.
134
 
 *
135
 
 * @param dlg           The underlying dialog to use.
136
 
 * @param user_cb       Pointer to callbacks to receive presence subscription
137
 
 *                      events.
138
 
 * @param rdata         The incoming SUBSCRIBE request that creates the event 
139
 
 *                      subscription.
140
 
 * @param p_evsub       Pointer to receive the presence subscription
141
 
 *                      session.
142
 
 *
143
 
 * @return              PJ_SUCCESS on success.
144
 
 */
145
 
PJ_DECL(pj_status_t) pjsip_pres_create_uas( pjsip_dialog *dlg,
146
 
                                            const pjsip_evsub_user *user_cb,
147
 
                                            pjsip_rx_data *rdata,
148
 
                                            pjsip_evsub **p_evsub );
149
 
 
150
 
 
151
 
/**
152
 
 * Forcefully destroy the presence subscription. This function should only
153
 
 * be called on special condition, such as when the subscription 
154
 
 * initialization has failed. For other conditions, application MUST terminate
155
 
 * the subscription by sending the appropriate un(SUBSCRIBE) or NOTIFY.
156
 
 *
157
 
 * @param sub           The presence subscription.
158
 
 * @param notify        Specify whether the state notification callback
159
 
 *                      should be called.
160
 
 *
161
 
 * @return              PJ_SUCCESS if subscription session has been destroyed.
162
 
 */
163
 
PJ_DECL(pj_status_t) pjsip_pres_terminate( pjsip_evsub *sub,
164
 
                                           pj_bool_t notify );
165
 
 
166
 
 
167
 
 
168
 
/**
169
 
 * Call this function to create request to initiate presence subscription, to 
170
 
 * refresh subcription, or to request subscription termination.
171
 
 *
172
 
 * @param sub           Client subscription instance.
173
 
 * @param expires       Subscription expiration. If the value is set to zero,
174
 
 *                      this will request unsubscription.
175
 
 * @param p_tdata       Pointer to receive the request.
176
 
 *
177
 
 * @return              PJ_SUCCESS on success.
178
 
 */
179
 
PJ_DECL(pj_status_t) pjsip_pres_initiate( pjsip_evsub *sub,
180
 
                                          pj_int32_t expires,
181
 
                                          pjsip_tx_data **p_tdata);
182
 
 
183
 
 
184
 
/**
185
 
 * Add a list of headers to the subscription instance. The list of headers
186
 
 * will be added to outgoing presence subscription requests.
187
 
 *
188
 
 * @param sub           Subscription instance.
189
 
 * @param hdr_list      List of headers to be added.
190
 
 *
191
 
 * @return              PJ_SUCCESS on success.
192
 
 */
193
 
PJ_DECL(pj_status_t) pjsip_pres_add_header( pjsip_evsub *sub,
194
 
                                            const pjsip_hdr *hdr_list );
195
 
 
196
 
 
197
 
/**
198
 
 * Accept the incoming subscription request by sending 2xx response to
199
 
 * incoming SUBSCRIBE request.
200
 
 *
201
 
 * @param sub           Server subscription instance.
202
 
 * @param rdata         The incoming subscription request message.
203
 
 * @param st_code       Status code, which MUST be final response.
204
 
 * @param hdr_list      Optional list of headers to be added in the response.
205
 
 *
206
 
 * @return              PJ_SUCCESS on success.
207
 
 */
208
 
PJ_DECL(pj_status_t) pjsip_pres_accept( pjsip_evsub *sub,
209
 
                                        pjsip_rx_data *rdata,
210
 
                                        int st_code,
211
 
                                        const pjsip_hdr *hdr_list );
212
 
 
213
 
 
214
 
 
215
 
 
216
 
/**
217
 
 * For notifier, create NOTIFY request to subscriber, and set the state 
218
 
 * of the subscription. Application MUST set the presence status to the
219
 
 * appropriate state (by calling #pjsip_pres_set_status()) before calling
220
 
 * this function.
221
 
 *
222
 
 * @param sub           The server subscription (notifier) instance.
223
 
 * @param state         New state to set.
224
 
 * @param state_str     The state string name, if state contains value other
225
 
 *                      than active, pending, or terminated. Otherwise this
226
 
 *                      argument is ignored.
227
 
 * @param reason        Specify reason if new state is terminated, otherwise
228
 
 *                      put NULL.
229
 
 * @param p_tdata       Pointer to receive the request.
230
 
 *
231
 
 * @return              PJ_SUCCESS on success.
232
 
 */
233
 
PJ_DECL(pj_status_t) pjsip_pres_notify( pjsip_evsub *sub,
234
 
                                        pjsip_evsub_state state,
235
 
                                        const pj_str_t *state_str,
236
 
                                        const pj_str_t *reason,
237
 
                                        pjsip_tx_data **p_tdata);
238
 
 
239
 
 
240
 
/**
241
 
 * Create NOTIFY request to reflect current subscription status.
242
 
 *
243
 
 * @param sub           Server subscription object.
244
 
 * @param p_tdata       Pointer to receive request.
245
 
 *
246
 
 * @return              PJ_SUCCESS on success.
247
 
 */
248
 
PJ_DECL(pj_status_t) pjsip_pres_current_notify( pjsip_evsub *sub,
249
 
                                                pjsip_tx_data **p_tdata );
250
 
 
251
 
 
252
 
 
253
 
/**
254
 
 * Send request message that was previously created with initiate(), notify(),
255
 
 * or current_notify(). Application may also send request created with other
256
 
 * functions, e.g. authentication. But the request MUST be either request
257
 
 * that creates/refresh subscription or NOTIFY request.
258
 
 *
259
 
 * @param sub           The subscription object.
260
 
 * @param tdata         Request message to be sent.
261
 
 *
262
 
 * @return              PJ_SUCCESS on success.
263
 
 */
264
 
PJ_DECL(pj_status_t) pjsip_pres_send_request( pjsip_evsub *sub,
265
 
                                              pjsip_tx_data *tdata );
266
 
 
267
 
 
268
 
/**
269
 
 * Get the presence status. Client normally would call this function
270
 
 * after receiving NOTIFY request from server.
271
 
 *
272
 
 * @param sub           The client or server subscription.
273
 
 * @param status        The structure to receive presence status.
274
 
 *
275
 
 * @return              PJ_SUCCESS on success.
276
 
 */
277
 
PJ_DECL(pj_status_t) pjsip_pres_get_status( pjsip_evsub *sub,
278
 
                                            pjsip_pres_status *status );
279
 
 
280
 
 
281
 
/**
282
 
 * Set the presence status. This operation is only valid for server
283
 
 * subscription. After calling this function, application would need to
284
 
 * send NOTIFY request to client.
285
 
 *
286
 
 * @param sub           The server subscription.
287
 
 * @param status        Status to be set.
288
 
 *
289
 
 * @return              PJ_SUCCESS on success.
290
 
 */
291
 
PJ_DECL(pj_status_t) pjsip_pres_set_status( pjsip_evsub *sub,
292
 
                                            const pjsip_pres_status *status );
293
 
 
294
 
 
295
 
/**
296
 
 * This is a utility function to create PIDF message body from PJSIP
297
 
 * presence status (pjsip_pres_status).
298
 
 *
299
 
 * @param pool          The pool to allocate memory for the message body.
300
 
 * @param status        Presence status to be converted into PIDF message
301
 
 *                      body.
302
 
 * @param entity        The entity ID, which normally is equal to the 
303
 
 *                      presentity ID publishing this presence info.
304
 
 * @param p_body        Pointer to receive the SIP message body.
305
 
 *
306
 
 * @return              PJ_SUCCESS on success.
307
 
 */
308
 
PJ_DECL(pj_status_t) pjsip_pres_create_pidf( pj_pool_t *pool,
309
 
                                             const pjsip_pres_status *status,
310
 
                                             const pj_str_t *entity,
311
 
                                             pjsip_msg_body **p_body );
312
 
 
313
 
 
314
 
/**
315
 
 * This is a utility function to create X-PIDF message body from PJSIP
316
 
 * presence status (pjsip_pres_status).
317
 
 *
318
 
 * @param pool          The pool to allocate memory for the message body.
319
 
 * @param status        Presence status to be converted into X-PIDF message
320
 
 *                      body.
321
 
 * @param entity        The entity ID, which normally is equal to the 
322
 
 *                      presentity ID publishing this presence info.
323
 
 * @param p_body        Pointer to receive the SIP message body.
324
 
 *
325
 
 * @return              PJ_SUCCESS on success.
326
 
 */
327
 
PJ_DECL(pj_status_t) pjsip_pres_create_xpidf(pj_pool_t *pool,
328
 
                                             const pjsip_pres_status *status,
329
 
                                             const pj_str_t *entity,
330
 
                                             pjsip_msg_body **p_body );
331
 
 
332
 
 
333
 
 
334
 
/**
335
 
 * This is a utility function to parse PIDF body into PJSIP presence status.
336
 
 *
337
 
 * @param rdata         The incoming SIP message containing the PIDF body.
338
 
 * @param pool          Pool to allocate memory to copy the strings into
339
 
 *                      the presence status structure.
340
 
 * @param status        The presence status to be initialized.
341
 
 *
342
 
 * @return              PJ_SUCCESS on success.
343
 
 *
344
 
 * @see pjsip_pres_parse_pidf2()
345
 
 */
346
 
PJ_DECL(pj_status_t) pjsip_pres_parse_pidf(pjsip_rx_data *rdata,
347
 
                                           pj_pool_t *pool,
348
 
                                           pjsip_pres_status *status);
349
 
 
350
 
/**
351
 
 * This is a utility function to parse PIDF body into PJSIP presence status.
352
 
 *
353
 
 * @param body          Text body, with one extra space at the end to place
354
 
 *                      NULL character temporarily during parsing.
355
 
 * @param body_len      Length of the body, not including the NULL termination
356
 
 *                      character.
357
 
 * @param pool          Pool to allocate memory to copy the strings into
358
 
 *                      the presence status structure.
359
 
 * @param status        The presence status to be initialized.
360
 
 *
361
 
 * @return              PJ_SUCCESS on success.
362
 
 *
363
 
 * @see pjsip_pres_parse_pidf()
364
 
 */
365
 
PJ_DECL(pj_status_t) pjsip_pres_parse_pidf2(char *body, unsigned body_len,
366
 
                                            pj_pool_t *pool,
367
 
                                            pjsip_pres_status *status);
368
 
 
369
 
 
370
 
/**
371
 
 * This is a utility function to parse X-PIDF body into PJSIP presence status.
372
 
 *
373
 
 * @param rdata         The incoming SIP message containing the X-PIDF body.
374
 
 * @param pool          Pool to allocate memory to copy the strings into
375
 
 *                      the presence status structure.
376
 
 * @param status        The presence status to be initialized.
377
 
 *
378
 
 * @return              PJ_SUCCESS on success.
379
 
 *
380
 
 * @see pjsip_pres_parse_xpidf2()
381
 
 */
382
 
PJ_DECL(pj_status_t) pjsip_pres_parse_xpidf(pjsip_rx_data *rdata,
383
 
                                           pj_pool_t *pool,
384
 
                                           pjsip_pres_status *status);
385
 
 
386
 
 
387
 
/**
388
 
 * This is a utility function to parse X-PIDF body into PJSIP presence status.
389
 
 *
390
 
 * @param body          Text body, with one extra space at the end to place
391
 
 *                      NULL character temporarily during parsing.
392
 
 * @param body_len      Length of the body, not including the NULL termination
393
 
 *                      character.
394
 
 * @param pool          Pool to allocate memory to copy the strings into
395
 
 *                      the presence status structure.
396
 
 * @param status        The presence status to be initialized.
397
 
 *
398
 
 * @return              PJ_SUCCESS on success.
399
 
 *
400
 
 * @see pjsip_pres_parse_xpidf()
401
 
 */
402
 
PJ_DECL(pj_status_t) pjsip_pres_parse_xpidf2(char *body, unsigned body_len,
403
 
                                             pj_pool_t *pool,
404
 
                                             pjsip_pres_status *status);
405
 
 
406
 
 
407
 
 
408
 
/**
409
 
 * @}
410
 
 */
411
 
 
412
 
PJ_END_DECL
413
 
 
414
 
 
415
 
#endif  /* __PJSIP_SIMPLE_PRESENCE_H__ */