← 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/evsub.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/pjsip/include/pjsip-simple/evsub.h
 
1
/* $Id: evsub.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_EVSUB_H__
 
21
#define __PJSIP_SIMPLE_EVSUB_H__
 
22
 
 
23
/**
 
24
 * @file evsub.h
 
25
 * @brief SIP Specific Event Notification Extension (RFC 3265)
 
26
 */
 
27
 
 
28
#include <pjsip-simple/types.h>
 
29
 
 
30
 
 
31
/**
 
32
 * @defgroup PJSIP_EVENT_NOT SIP Event Notification (RFC 3265) Module
 
33
 * @ingroup PJSIP_SIMPLE
 
34
 * @brief Core Event Subscription framework, used by presence, call transfer, etc.
 
35
 * @{
 
36
 *
 
37
 * This module provides the implementation of SIP Extension for SIP Specific
 
38
 * Event Notification (RFC 3265). It extends PJSIP by supporting SUBSCRIBE and
 
39
 * NOTIFY methods.
 
40
 *
 
41
 * This module itself is extensible; new event packages can be registered to
 
42
 * this module to handle specific extensions (such as presence).
 
43
 */
 
44
 
 
45
PJ_BEGIN_DECL
 
46
 
 
47
 
 
48
/**
 
49
 * Opaque type for event subscription session.
 
50
 */
 
51
typedef struct pjsip_evsub pjsip_evsub;
 
52
 
 
53
 
 
54
/**
 
55
 * This enumeration describes basic subscription state as described in the 
 
56
 * RFC 3265. The standard specifies that extensions may define additional 
 
57
 * states. In the case where the state is not known, the subscription state
 
58
 * will be set to PJSIP_EVSUB_STATE_UNKNOWN, and the token will be kept
 
59
 * in state_str member of the susbcription structure.
 
60
 */
 
61
enum pjsip_evsub_state
 
62
{
 
63
    PJSIP_EVSUB_STATE_NULL,      /**< State is NULL.                        */
 
64
    PJSIP_EVSUB_STATE_SENT,      /**< Client has sent SUBSCRIBE request.    */
 
65
    PJSIP_EVSUB_STATE_ACCEPTED,  /**< 2xx response to SUBSCRIBE has been 
 
66
                                      sent/received.                        */
 
67
    PJSIP_EVSUB_STATE_PENDING,   /**< Subscription is pending.              */
 
68
    PJSIP_EVSUB_STATE_ACTIVE,    /**< Subscription is active.               */
 
69
    PJSIP_EVSUB_STATE_TERMINATED,/**< Subscription is terminated.           */
 
70
    PJSIP_EVSUB_STATE_UNKNOWN,   /**< Subscription state can not be determined.
 
71
                                      Application can query the state by 
 
72
                                      calling #pjsip_evsub_get_state_name().*/
 
73
};
 
74
 
 
75
/**
 
76
 * @see pjsip_evsub_state
 
77
 */
 
78
typedef enum pjsip_evsub_state pjsip_evsub_state;
 
79
 
 
80
 
 
81
/**
 
82
 * Some options for the event subscription.
 
83
 */
 
84
enum
 
85
{
 
86
    /** 
 
87
     * If this flag is set, then outgoing request to create subscription
 
88
     * will not have id in the Event header (e.g. in REFER request). But if 
 
89
     * there is an id in the incoming NOTIFY, that id will be used.
 
90
     */
 
91
    PJSIP_EVSUB_NO_EVENT_ID  = 1,
 
92
};
 
93
 
 
94
 
 
95
/**
 
96
 * This structure describes callback that is registered by application or
 
97
 * package to receive notifications about subscription events.
 
98
 */
 
99
struct pjsip_evsub_user
 
100
{
 
101
    /**
 
102
     * This callback is called when subscription state has changed.
 
103
     * Application MUST be prepared to receive NULL event and events with
 
104
     * type other than PJSIP_EVENT_TSX_STATE
 
105
     *
 
106
     * This callback is OPTIONAL.
 
107
     *
 
108
     * @param sub       The subscription instance.
 
109
     * @param event     The event that has caused the state to change,
 
110
     *                  which may be NULL or may have type other than
 
111
     *                  PJSIP_EVENT_TSX_STATE.
 
112
     */
 
113
    void (*on_evsub_state)( pjsip_evsub *sub, pjsip_event *event);
 
114
 
 
115
    /**
 
116
     * This callback is called when transaction state has changed.
 
117
     *
 
118
     * @param sub       The subscription instance.
 
119
     * @param tsx       Transaction.
 
120
     * @param event     The event.
 
121
     */
 
122
    void (*on_tsx_state)(pjsip_evsub *sub, pjsip_transaction *tsx,
 
123
                         pjsip_event *event);
 
124
 
 
125
    /**
 
126
     * This callback is called when incoming SUBSCRIBE (or any method that
 
127
     * establishes the subscription in the first place) is received. It 
 
128
     * allows application to specify what response should be sent to 
 
129
     * remote, along with additional headers and message body to be put 
 
130
     * in the response.
 
131
     *
 
132
     * This callback is OPTIONAL.
 
133
     *
 
134
     * However, implementation MUST send NOTIFY request upon receiving this
 
135
     * callback. The suggested behavior is to call 
 
136
     * #pjsip_evsub_current_notify(), since this function takes care
 
137
     * about unsubscription request and calculates the appropriate expiration
 
138
     * interval.
 
139
     */
 
140
    void (*on_rx_refresh)( pjsip_evsub *sub, 
 
141
                           pjsip_rx_data *rdata,
 
142
                           int *p_st_code,
 
143
                           pj_str_t **p_st_text,
 
144
                           pjsip_hdr *res_hdr,
 
145
                           pjsip_msg_body **p_body);
 
146
 
 
147
    /**
 
148
     * This callback is called when client/subscriber received incoming
 
149
     * NOTIFY request. It allows the application to specify what response
 
150
     * should be sent to remote, along with additional headers and message
 
151
     * body to be put in the response.
 
152
     *
 
153
     * This callback is OPTIONAL. When it is not implemented, the default
 
154
     * behavior is to respond incoming NOTIFY request with 200 (OK).
 
155
     *
 
156
     * @param sub       The subscription instance.
 
157
     * @param rdata     The received NOTIFY request.
 
158
     * @param p_st_code Application MUST set the value of this argument with
 
159
     *                  final status code (200-699) upon returning from the
 
160
     *                  callback.
 
161
     * @param p_st_text Custom status text, if any.
 
162
     * @param res_hdr   Upon return, application can put additional headers 
 
163
     *                  to be sent in the response in this list.
 
164
     * @param p_body    Application MAY specify message body to be sent in
 
165
     *                  the response.
 
166
     */
 
167
    void (*on_rx_notify)(pjsip_evsub *sub, 
 
168
                         pjsip_rx_data *rdata,
 
169
                         int *p_st_code,
 
170
                         pj_str_t **p_st_text,
 
171
                         pjsip_hdr *res_hdr,
 
172
                         pjsip_msg_body **p_body);
 
173
 
 
174
    /**
 
175
     * This callback is called when it is time for the client to refresh
 
176
     * the subscription.
 
177
     *
 
178
     * This callback is OPTIONAL when PJSIP package such as presence or 
 
179
     * refer is used; the event package will refresh subscription by sending
 
180
     * SUBSCRIBE with the interval set to current/last interval.
 
181
     *
 
182
     * @param sub       The subscription instance.
 
183
     */
 
184
    void (*on_client_refresh)(pjsip_evsub *sub);
 
185
 
 
186
    /**
 
187
     * This callback is called when server doesn't receive subscription 
 
188
     * refresh after the specified subscription interval.
 
189
     *
 
190
     * This callback is OPTIONAL when PJSIP package such as presence or 
 
191
     * refer is used; the event package send NOTIFY to terminate the 
 
192
     * subscription.
 
193
     */
 
194
    void (*on_server_timeout)(pjsip_evsub *sub);
 
195
 
 
196
};
 
197
 
 
198
 
 
199
/**
 
200
 * @see pjsip_evsub_user
 
201
 */
 
202
typedef struct pjsip_evsub_user pjsip_evsub_user;
 
203
 
 
204
 
 
205
/**
 
206
 * SUBSCRIBE method constant. @see pjsip_get_subscribe_method()
 
207
 */
 
208
PJ_DECL_DATA(const pjsip_method) pjsip_subscribe_method;
 
209
 
 
210
/**
 
211
 * NOTIFY method constant. @see pjsip_get_notify_method()
 
212
 */
 
213
PJ_DECL_DATA(const pjsip_method) pjsip_notify_method;
 
214
 
 
215
/**
 
216
 * SUBSCRIBE method constant.
 
217
 */
 
218
PJ_DECL(const pjsip_method*) pjsip_get_subscribe_method(void);
 
219
 
 
220
/**
 
221
 * NOTIFY method constant.
 
222
 */
 
223
PJ_DECL(const pjsip_method*) pjsip_get_notify_method(void);
 
224
 
 
225
 
 
226
/**
 
227
 * Initialize the event subscription module and register the module to the 
 
228
 * specified endpoint.
 
229
 *
 
230
 * @param endpt         The endpoint instance.
 
231
 *
 
232
 * @return              PJ_SUCCESS if module can be created and registered
 
233
 *                      successfully.
 
234
 */
 
235
PJ_DECL(pj_status_t) pjsip_evsub_init_module(pjsip_endpoint *endpt);
 
236
 
 
237
 
 
238
/**
 
239
 * Get the event subscription module instance that was previously created 
 
240
 * and registered to endpoint.
 
241
 *
 
242
 * @return              The event subscription module instance.
 
243
 */
 
244
PJ_DECL(pjsip_module*) pjsip_evsub_instance(void);
 
245
 
 
246
 
 
247
/**
 
248
 * Register event package to the event subscription framework.
 
249
 *
 
250
 * @param pkg_mod       The module that implements the event package being
 
251
 *                      registered.
 
252
 * @param event_name    Event package identification.
 
253
 * @param expires       Default subscription expiration time, in seconds.
 
254
 * @param accept_cnt    Number of strings in Accept array.
 
255
 * @param accept        Array of Accept value.
 
256
 *
 
257
 * @return              PJ_SUCCESS on success.
 
258
 */
 
259
PJ_DECL(pj_status_t) pjsip_evsub_register_pkg( pjsip_module *pkg_mod,
 
260
                                               const pj_str_t *event_name,
 
261
                                               unsigned expires,
 
262
                                               unsigned accept_cnt,
 
263
                                               const pj_str_t accept[]);
 
264
 
 
265
/**
 
266
 * Get the Allow-Events header. This header is built based on the packages
 
267
 * that are registered to the evsub module.
 
268
 *
 
269
 * @param m             Pointer to event subscription module instance, or
 
270
 *                      NULL to use default instance (equal to 
 
271
 *                      #pjsip_evsub_instance()).
 
272
 *
 
273
 * @return              The Allow-Events header.
 
274
 */
 
275
PJ_DECL(const pjsip_hdr*) pjsip_evsub_get_allow_events_hdr(pjsip_module *m);
 
276
 
 
277
 
 
278
/**
 
279
 * Create client subscription session.
 
280
 *
 
281
 * @param dlg           The underlying dialog to use.
 
282
 * @param user_cb       Callback to receive event subscription notifications.
 
283
 * @param event         Event name.
 
284
 * @param option        Bitmask of options.
 
285
 * @param p_evsub       Pointer to receive event subscription instance.
 
286
 *
 
287
 * @return              PJ_SUCCESS on success.
 
288
 */
 
289
PJ_DECL(pj_status_t) pjsip_evsub_create_uac( pjsip_dialog *dlg,
 
290
                                             const pjsip_evsub_user *user_cb,
 
291
                                             const pj_str_t *event,
 
292
                                             unsigned option,
 
293
                                             pjsip_evsub **p_evsub);
 
294
 
 
295
/**
 
296
 * Create server subscription session.
 
297
 *
 
298
 * @param dlg           The underlying dialog to use.
 
299
 * @param user_cb       Callback to receive event subscription notifications.
 
300
 * @param rdata         The incoming request that creates the event 
 
301
 *                      subscription, such as SUBSCRIBE or REFER.
 
302
 * @param option        Bitmask of options.
 
303
 * @param p_evsub       Pointer to receive event subscription instance.
 
304
 *
 
305
 * @return              PJ_SUCCESS on success.
 
306
 */
 
307
PJ_DECL(pj_status_t) pjsip_evsub_create_uas( pjsip_dialog *dlg,
 
308
                                             const pjsip_evsub_user *user_cb,
 
309
                                             pjsip_rx_data *rdata,
 
310
                                             unsigned option,
 
311
                                             pjsip_evsub **p_evsub);
 
312
 
 
313
/**
 
314
 * Forcefully destroy the subscription session. This function should only
 
315
 * be called on special condition, such as when the subscription 
 
316
 * initialization has failed. For other conditions, application MUST terminate
 
317
 * the subscription by sending the appropriate un(SUBSCRIBE) or NOTIFY.
 
318
 *
 
319
 * @param sub           The event subscription.
 
320
 * @param notify        Specify whether the state notification callback
 
321
 *                      should be called.
 
322
 *
 
323
 * @return              PJ_SUCCESS if subscription session has been destroyed.
 
324
 */
 
325
PJ_DECL(pj_status_t) pjsip_evsub_terminate( pjsip_evsub *sub,
 
326
                                            pj_bool_t notify );
 
327
 
 
328
 
 
329
/**
 
330
 * Get subscription state.
 
331
 *
 
332
 * @param sub           Event subscription instance.
 
333
 *
 
334
 * @return              Subscription state.
 
335
 */
 
336
PJ_DECL(pjsip_evsub_state) pjsip_evsub_get_state(pjsip_evsub *sub);
 
337
 
 
338
 
 
339
/**
 
340
 * Get the string representation of the subscription state.
 
341
 *
 
342
 * @param sub           Event subscription instance.
 
343
 *
 
344
 * @return              NULL terminated string.
 
345
 */
 
346
PJ_DECL(const char*) pjsip_evsub_get_state_name(pjsip_evsub *sub);
 
347
 
 
348
 
 
349
/**
 
350
 * Get subscription termination reason, if any. If remote did not
 
351
 * send termination reason, this function will return empty string.
 
352
 *
 
353
 * @param sub           Event subscription instance.
 
354
 *
 
355
 * @return              NULL terminated string.
 
356
 */
 
357
PJ_DECL(const pj_str_t*) pjsip_evsub_get_termination_reason(pjsip_evsub *sub);
 
358
 
 
359
 
 
360
/**
 
361
 * Call this function to create request to initiate subscription, to 
 
362
 * refresh subcription, or to request subscription termination.
 
363
 *
 
364
 * @param sub           Client subscription instance.
 
365
 * @param method        The method that establishes the subscription, such as
 
366
 *                      SUBSCRIBE or REFER. If this argument is NULL, then
 
367
 *                      SUBSCRIBE will be used.
 
368
 * @param expires       Subscription expiration. If the value is set to zero,
 
369
 *                      this will request unsubscription. If the value is
 
370
 *                      negative, default expiration as defined by the package
 
371
 *                      will be used.
 
372
 * @param p_tdata       Pointer to receive the request.
 
373
 *
 
374
 * @return              PJ_SUCCESS on success.
 
375
 */
 
376
PJ_DECL(pj_status_t) pjsip_evsub_initiate( pjsip_evsub *sub,
 
377
                                           const pjsip_method *method,
 
378
                                           pj_int32_t expires,
 
379
                                           pjsip_tx_data **p_tdata);
 
380
 
 
381
 
 
382
/**
 
383
 * Add a list of headers to the subscription instance. The list of headers
 
384
 * will be added to outgoing presence subscription requests.
 
385
 *
 
386
 * @param sub           Subscription instance.
 
387
 * @param hdr_list      List of headers to be added.
 
388
 *
 
389
 * @return              PJ_SUCCESS on success.
 
390
 */
 
391
PJ_DECL(pj_status_t) pjsip_evsub_add_header( pjsip_evsub *sub,
 
392
                                             const pjsip_hdr *hdr_list );
 
393
 
 
394
 
 
395
/**
 
396
 * Accept the incoming subscription request by sending 2xx response to
 
397
 * incoming SUBSCRIBE request.
 
398
 *
 
399
 * @param sub           Server subscription instance.
 
400
 * @param rdata         The incoming subscription request message.
 
401
 * @param st_code       Status code, which MUST be final response.
 
402
 * @param hdr_list      Optional list of headers to be added in the response.
 
403
 *
 
404
 * @return              PJ_SUCCESS on success.
 
405
 */
 
406
PJ_DECL(pj_status_t) pjsip_evsub_accept( pjsip_evsub *sub,
 
407
                                         pjsip_rx_data *rdata,
 
408
                                         int st_code,
 
409
                                         const pjsip_hdr *hdr_list );
 
410
 
 
411
 
 
412
/**
 
413
 * For notifier, create NOTIFY request to subscriber, and set the state 
 
414
 * of the subscription.
 
415
 *
 
416
 * @param sub           The server subscription (notifier) instance.
 
417
 * @param state         New state to set.
 
418
 * @param state_str     The state string name, if state contains value other
 
419
 *                      than active, pending, or terminated. Otherwise this
 
420
 *                      argument is ignored.
 
421
 * @param reason        Specify reason if new state is terminated, otherwise
 
422
 *                      put NULL.
 
423
 * @param p_tdata       Pointer to receive request message.
 
424
 *
 
425
 * @return              PJ_SUCCESS on success.
 
426
 */
 
427
PJ_DECL(pj_status_t) pjsip_evsub_notify( pjsip_evsub *sub,
 
428
                                         pjsip_evsub_state state,
 
429
                                         const pj_str_t *state_str,
 
430
                                         const pj_str_t *reason,
 
431
                                         pjsip_tx_data **p_tdata);
 
432
 
 
433
 
 
434
/**
 
435
 * For notifier, create a NOTIFY request that reflects current subscription
 
436
 * status.
 
437
 *
 
438
 * @param sub           The server subscription instance.
 
439
 * @param p_tdata       Pointer to receive the request messge.
 
440
 *
 
441
 * @return              PJ_SUCCESS on success.
 
442
 */
 
443
PJ_DECL(pj_status_t) pjsip_evsub_current_notify( pjsip_evsub *sub,
 
444
                                                 pjsip_tx_data **p_tdata );
 
445
 
 
446
 
 
447
 
 
448
/**
 
449
 * Send request message that was previously created with initiate(), notify(),
 
450
 * or current_notify(). Application may also send request created with other
 
451
 * functions, e.g. authentication. But the request MUST be either request
 
452
 * that creates/refresh subscription or NOTIFY request.
 
453
 *
 
454
 * @param sub           The event subscription object.
 
455
 * @param tdata         Request message to be send.
 
456
 *
 
457
 * @return              PJ_SUCCESS on success.
 
458
 */
 
459
PJ_DECL(pj_status_t) pjsip_evsub_send_request( pjsip_evsub *sub,
 
460
                                               pjsip_tx_data *tdata);
 
461
 
 
462
 
 
463
 
 
464
/**
 
465
 * Get the event subscription instance associated with the specified 
 
466
 * transaction.
 
467
 *
 
468
 * @param tsx           The transaction.
 
469
 *
 
470
 * @return              The event subscription instance registered in the
 
471
 *                      transaction, if any.
 
472
 */
 
473
PJ_DECL(pjsip_evsub*) pjsip_tsx_get_evsub(pjsip_transaction *tsx);
 
474
 
 
475
 
 
476
/**
 
477
 * Set event subscription's module data.
 
478
 *
 
479
 * @param sub           The event subscription.
 
480
 * @param mod_id        The module id.
 
481
 * @param data          Arbitrary data.
 
482
 */
 
483
PJ_DECL(void) pjsip_evsub_set_mod_data( pjsip_evsub *sub, unsigned mod_id,
 
484
                                        void *data );
 
485
 
 
486
 
 
487
/**
 
488
 * Get event subscription's module data.
 
489
 *
 
490
 * @param sub           The event subscription.
 
491
 * @param mod_id        The module id.
 
492
 *
 
493
 * @return              Data previously set at the specified id.
 
494
 */
 
495
PJ_DECL(void*) pjsip_evsub_get_mod_data( pjsip_evsub *sub, unsigned mod_id );
 
496
 
 
497
 
 
498
 
 
499
PJ_END_DECL
 
500
 
 
501
/**
 
502
 * @}
 
503
 */
 
504
 
 
505
#endif  /* __PJSIP_SIMPLE_EVSUB_H__ */