← Back to branch summary

~ubuntu-branches/ubuntu/trusty/sflphone/trusty

« back to all changes in this revision

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

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (4.3.4 sid)
  • Revision ID: package-import@ubuntu.com-20140128182336-jrsv0k9u6cawc068
Tags: 1.3.0-1
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.0.1/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__ */