← Back to branch summary

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

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.2.1/pjsip/include/pjsua2/account.hpp

  • 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.2.1/pjsip/include/pjsua2/account.hpp
 
1
/* $Id: account.hpp 4704 2014-01-16 05:30:46Z ming $ */
 
2
/*
 
3
 * Copyright (C) 2013 Teluu Inc. (http://www.teluu.com)
 
4
 *
 
5
 * This program is free software; you can redistribute it and/or modify
 
6
 * it under the terms of the GNU General Public License as published by
 
7
 * the Free Software Foundation; either version 2 of the License, or
 
8
 * (at your option) any later version.
 
9
 *
 
10
 * This program is distributed in the hope that it will be useful,
 
11
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 
12
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
13
 * GNU General Public License for more details.
 
14
 *
 
15
 * You should have received a copy of the GNU General Public License
 
16
 * along with this program; if not, write to the Free Software
 
17
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
18
 */
 
19
#ifndef __PJSUA2_ACCOUNT_HPP__
 
20
#define __PJSUA2_ACCOUNT_HPP__
 
21
 
 
22
/**
 
23
 * @file pjsua2/account.hpp
 
24
 * @brief PJSUA2 Account operations
 
25
 */
 
26
#include <pjsua-lib/pjsua.h>
 
27
#include <pjsua2/persistent.hpp>
 
28
#include <pjsua2/presence.hpp>
 
29
#include <pjsua2/siptypes.hpp>
 
30
 
 
31
/** PJSUA2 API is inside pj namespace */
 
32
namespace pj
 
33
{
 
34
 
 
35
/**
 
36
 * @defgroup PJSUA2_ACC Account
 
37
 * @ingroup PJSUA2_Ref
 
38
 * @{
 
39
 */
 
40
 
 
41
using std::string;
 
42
 
 
43
/**
 
44
 * Account registration config. This will be specified in AccountConfig.
 
45
 */
 
46
struct AccountRegConfig : public PersistentObject
 
47
{
 
48
    /**
 
49
     * This is the URL to be put in the request URI for the registration,
 
50
     * and will look something like "sip:serviceprovider".
 
51
     *
 
52
     * This field should be specified if registration is desired. If the
 
53
     * value is empty, no account registration will be performed.
 
54
     */
 
55
    string              registrarUri;
 
56
 
 
57
    /**
 
58
     * Specify whether the account should register as soon as it is
 
59
     * added to the UA. Application can set this to PJ_FALSE and control
 
60
     * the registration manually with pjsua_acc_set_registration().
 
61
     *
 
62
     * Default: True
 
63
     */
 
64
    bool                registerOnAdd;
 
65
 
 
66
    /**
 
67
     * The optional custom SIP headers to be put in the registration
 
68
     * request.
 
69
     */
 
70
    SipHeaderVector     headers;
 
71
 
 
72
    /**
 
73
     * Optional interval for registration, in seconds. If the value is zero,
 
74
     * default interval will be used (PJSUA_REG_INTERVAL, 300 seconds).
 
75
     */
 
76
    unsigned            timeoutSec;
 
77
 
 
78
    /**
 
79
     * Specify interval of auto registration retry upon registration failure
 
80
     * (including caused by transport problem), in second. Set to 0 to
 
81
     * disable auto re-registration. Note that if the registration retry
 
82
     * occurs because of transport failure, the first retry will be done
 
83
     * after \a firstRetryIntervalSec seconds instead. Also note that
 
84
     * the interval will be randomized slightly by approximately +/- ten
 
85
     * seconds to avoid all clients re-registering at the same time.
 
86
     *
 
87
     * See also \a firstRetryIntervalSec setting.
 
88
     *
 
89
     * Default: PJSUA_REG_RETRY_INTERVAL
 
90
     */
 
91
    unsigned            retryIntervalSec;
 
92
 
 
93
    /**
 
94
     * This specifies the interval for the first registration retry. The
 
95
     * registration retry is explained in \a retryIntervalSec. Note that
 
96
     * the value here will also be randomized by +/- ten seconds.
 
97
     *
 
98
     * Default: 0
 
99
     */
 
100
    unsigned            firstRetryIntervalSec;
 
101
 
 
102
    /**
 
103
     * Specify the number of seconds to refresh the client registration
 
104
     * before the registration expires.
 
105
     *
 
106
     * Default: PJSIP_REGISTER_CLIENT_DELAY_BEFORE_REFRESH, 5 seconds
 
107
     */
 
108
    unsigned            delayBeforeRefreshSec;
 
109
 
 
110
    /**
 
111
     * Specify whether calls of the configured account should be dropped
 
112
     * after registration failure and an attempt of re-registration has
 
113
     * also failed.
 
114
     *
 
115
     * Default: FALSE (disabled)
 
116
     */
 
117
    bool                dropCallsOnFail;
 
118
 
 
119
    /**
 
120
     * Specify the maximum time to wait for unregistration requests to
 
121
     * complete during library shutdown sequence.
 
122
     *
 
123
     * Default: PJSUA_UNREG_TIMEOUT
 
124
     */
 
125
    unsigned            unregWaitSec;
 
126
 
 
127
    /**
 
128
     * Specify how the registration uses the outbound and account proxy
 
129
     * settings. This controls if and what Route headers will appear in
 
130
     * the REGISTER request of this account. The value is bitmask combination
 
131
     * of PJSUA_REG_USE_OUTBOUND_PROXY and PJSUA_REG_USE_ACC_PROXY bits.
 
132
     * If the value is set to 0, the REGISTER request will not use any proxy
 
133
     * (i.e. it will not have any Route headers).
 
134
     *
 
135
     * Default: 3 (PJSUA_REG_USE_OUTBOUND_PROXY | PJSUA_REG_USE_ACC_PROXY)
 
136
     */
 
137
    unsigned            proxyUse;
 
138
 
 
139
public:
 
140
    /**
 
141
     * Read this object from a container node.
 
142
     *
 
143
     * @param node              Container to read values from.
 
144
     */
 
145
    virtual void readObject(const ContainerNode &node) throw(Error);
 
146
 
 
147
    /**
 
148
     * Write this object to a container node.
 
149
     *
 
150
     * @param node              Container to write values to.
 
151
     */
 
152
    virtual void writeObject(ContainerNode &node) const throw(Error);
 
153
 
 
154
};
 
155
 
 
156
/** Array of SIP credentials */
 
157
typedef std::vector<AuthCredInfo> AuthCredInfoVector;
 
158
 
 
159
/**
 
160
 * Various SIP settings for the account. This will be specified in
 
161
 * AccountConfig.
 
162
 */
 
163
struct AccountSipConfig : public PersistentObject
 
164
{
 
165
    /**
 
166
     * Array of credentials. If registration is desired, normally there should
 
167
     * be at least one credential specified, to successfully authenticate
 
168
     * against the service provider. More credentials can be specified, for
 
169
     * example when the requests are expected to be challenged by the
 
170
     * proxies in the route set.
 
171
     */
 
172
    AuthCredInfoVector  authCreds;
 
173
 
 
174
    /**
 
175
     * Array of proxy servers to visit for outgoing requests. Each of the
 
176
     * entry is translated into one Route URI.
 
177
     */
 
178
    StringVector        proxies;
 
179
 
 
180
    /**
 
181
     * Optional URI to be put as Contact for this account. It is recommended
 
182
     * that this field is left empty, so that the value will be calculated
 
183
     * automatically based on the transport address.
 
184
     */
 
185
    string              contactForced;
 
186
 
 
187
    /**
 
188
     * Additional parameters that will be appended in the Contact header
 
189
     * for this account. This will affect the Contact header in all SIP
 
190
     * messages sent on behalf of this account, including but not limited to
 
191
     * REGISTER, INVITE, and SUBCRIBE requests or responses.
 
192
     *
 
193
     * The parameters should be preceeded by semicolon, and all strings must
 
194
     * be properly escaped. Example:
 
195
     *   ";my-param=X;another-param=Hi%20there"
 
196
     */
 
197
    string              contactParams;
 
198
 
 
199
    /**
 
200
     * Additional URI parameters that will be appended in the Contact URI
 
201
     * for this account. This will affect the Contact URI in all SIP
 
202
     * messages sent on behalf of this account, including but not limited to
 
203
     * REGISTER, INVITE, and SUBCRIBE requests or responses.
 
204
     *
 
205
     * The parameters should be preceeded by semicolon, and all strings must
 
206
     * be properly escaped. Example:
 
207
     *   ";my-param=X;another-param=Hi%20there"
 
208
     */
 
209
    string              contactUriParams;
 
210
 
 
211
 
 
212
    /**
 
213
     * If this flag is set, the authentication client framework will
 
214
     * send an empty Authorization header in each initial request.
 
215
     * Default is no.
 
216
     */
 
217
    bool                authInitialEmpty;
 
218
 
 
219
    /**
 
220
     * Specify the algorithm to use when empty Authorization header
 
221
     * is to be sent for each initial request (see above)
 
222
     */
 
223
    string              authInitialAlgorithm;
 
224
 
 
225
    /**
 
226
     * Optionally bind this account to specific transport. This normally is
 
227
     * not a good idea, as account should be able to send requests using
 
228
     * any available transports according to the destination. But some
 
229
     * application may want to have explicit control over the transport to
 
230
     * use, so in that case it can set this field.
 
231
     *
 
232
     * Default: -1 (PJSUA_INVALID_ID)
 
233
     *
 
234
     * @see Account::setTransport()
 
235
     */
 
236
    TransportId         transportId;
 
237
 
 
238
public:
 
239
    /**
 
240
     * Read this object from a container node.
 
241
     *
 
242
     * @param node              Container to read values from.
 
243
     */
 
244
    virtual void readObject(const ContainerNode &node) throw(Error);
 
245
 
 
246
    /**
 
247
     * Write this object to a container node.
 
248
     *
 
249
     * @param node              Container to write values to.
 
250
     */
 
251
    virtual void writeObject(ContainerNode &node) const throw(Error);
 
252
};
 
253
 
 
254
/**
 
255
 * Account's call settings. This will be specified in AccountConfig.
 
256
 */
 
257
struct AccountCallConfig : public PersistentObject
 
258
{
 
259
    /**
 
260
     * Specify how to offer call hold to remote peer. Please see the
 
261
     * documentation on pjsua_call_hold_type for more info.
 
262
     *
 
263
     * Default: PJSUA_CALL_HOLD_TYPE_DEFAULT
 
264
     */
 
265
    pjsua_call_hold_type holdType;
 
266
 
 
267
    /**
 
268
     * Specify how support for reliable provisional response (100rel/
 
269
     * PRACK) should be used for all sessions in this account. See the
 
270
     * documentation of pjsua_100rel_use enumeration for more info.
 
271
     *
 
272
     * Default: PJSUA_100REL_NOT_USED
 
273
     */
 
274
    pjsua_100rel_use    prackUse;
 
275
 
 
276
    /**
 
277
     * Specify the usage of Session Timers for all sessions. See the
 
278
     * pjsua_sip_timer_use for possible values.
 
279
     *
 
280
     * Default: PJSUA_SIP_TIMER_OPTIONAL
 
281
     */
 
282
    pjsua_sip_timer_use timerUse;
 
283
 
 
284
    /**
 
285
     * Specify minimum Session Timer expiration period, in seconds.
 
286
     * Must not be lower than 90. Default is 90.
 
287
     */
 
288
    unsigned            timerMinSESec;
 
289
 
 
290
    /**
 
291
     * Specify Session Timer expiration period, in seconds.
 
292
     * Must not be lower than timerMinSE. Default is 1800.
 
293
     */
 
294
    unsigned            timerSessExpiresSec;
 
295
 
 
296
public:
 
297
    /**
 
298
     * Read this object from a container node.
 
299
     *
 
300
     * @param node              Container to read values from.
 
301
     */
 
302
    virtual void readObject(const ContainerNode &node) throw(Error);
 
303
 
 
304
    /**
 
305
     * Write this object to a container node.
 
306
     *
 
307
     * @param node              Container to write values to.
 
308
     */
 
309
    virtual void writeObject(ContainerNode &node) const throw(Error);
 
310
};
 
311
 
 
312
/**
 
313
 * Account presence config. This will be specified in AccountConfig.
 
314
 */
 
315
struct AccountPresConfig : public PersistentObject
 
316
{
 
317
    /**
 
318
     * The optional custom SIP headers to be put in the presence
 
319
     * subscription request.
 
320
     */
 
321
    SipHeaderVector     headers;
 
322
 
 
323
    /**
 
324
     * If this flag is set, the presence information of this account will
 
325
     * be PUBLISH-ed to the server where the account belongs.
 
326
     *
 
327
     * Default: PJ_FALSE
 
328
     */
 
329
    bool                publishEnabled;
 
330
 
 
331
    /**
 
332
     * Specify whether the client publication session should queue the
 
333
     * PUBLISH request should there be another PUBLISH transaction still
 
334
     * pending. If this is set to false, the client will return error
 
335
     * on the PUBLISH request if there is another PUBLISH transaction still
 
336
     * in progress.
 
337
     *
 
338
     * Default: PJSIP_PUBLISHC_QUEUE_REQUEST (TRUE)
 
339
     */
 
340
    bool                publishQueue;
 
341
 
 
342
    /**
 
343
     * Maximum time to wait for unpublication transaction(s) to complete
 
344
     * during shutdown process, before sending unregistration. The library
 
345
     * tries to wait for the unpublication (un-PUBLISH) to complete before
 
346
     * sending REGISTER request to unregister the account, during library
 
347
     * shutdown process. If the value is set too short, it is possible that
 
348
     * the unregistration is sent before unpublication completes, causing
 
349
     * unpublication request to fail.
 
350
     *
 
351
     * Value is in milliseconds.
 
352
     *
 
353
     * Default: PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC (2000)
 
354
     */
 
355
    unsigned            publishShutdownWaitMsec;
 
356
 
 
357
    /**
 
358
     * Optional PIDF tuple ID for outgoing PUBLISH and NOTIFY. If this value
 
359
     * is not specified, a random string will be used.
 
360
     */
 
361
    string              pidfTupleId;
 
362
 
 
363
public:
 
364
    /**
 
365
     * Read this object from a container node.
 
366
     *
 
367
     * @param node              Container to read values from.
 
368
     */
 
369
    virtual void readObject(const ContainerNode &node) throw(Error);
 
370
 
 
371
    /**
 
372
     * Write this object to a container node.
 
373
     *
 
374
     * @param node              Container to write values to.
 
375
     */
 
376
    virtual void writeObject(ContainerNode &node) const throw(Error);
 
377
};
 
378
 
 
379
/**
 
380
 * Account MWI (Message Waiting Indication) settings. This will be specified
 
381
 * in AccountConfig.
 
382
 */
 
383
struct AccountMwiConfig : public PersistentObject
 
384
{
 
385
    /**
 
386
     * Subscribe to message waiting indication events (RFC 3842).
 
387
     *
 
388
     * See also UaConfig.mwiUnsolicitedEnabled setting.
 
389
     *
 
390
     * Default: FALSE
 
391
     */
 
392
    bool                enabled;
 
393
 
 
394
    /**
 
395
     * Specify the default expiration time (in seconds) for Message
 
396
     * Waiting Indication (RFC 3842) event subscription. This must not
 
397
     * be zero.
 
398
     *
 
399
     * Default: PJSIP_MWI_DEFAULT_EXPIRES (3600)
 
400
     */
 
401
    unsigned            expirationSec;
 
402
 
 
403
public:
 
404
    /**
 
405
     * Read this object from a container node.
 
406
     *
 
407
     * @param node              Container to read values from.
 
408
     */
 
409
    virtual void readObject(const ContainerNode &node) throw(Error);
 
410
 
 
411
    /**
 
412
     * Write this object to a container node.
 
413
     *
 
414
     * @param node              Container to write values to.
 
415
     */
 
416
    virtual void writeObject(ContainerNode &node) const throw(Error);
 
417
};
 
418
 
 
419
/**
 
420
 * Account's NAT (Network Address Translation) settings. This will be
 
421
 * specified in AccountConfig.
 
422
 */
 
423
struct AccountNatConfig : public PersistentObject
 
424
{
 
425
    /**
 
426
     * Control the use of STUN for the SIP signaling.
 
427
     *
 
428
     * Default: PJSUA_STUN_USE_DEFAULT
 
429
     */
 
430
    pjsua_stun_use      sipStunUse;
 
431
 
 
432
    /**
 
433
     * Control the use of STUN for the media transports.
 
434
     *
 
435
     * Default: PJSUA_STUN_USE_DEFAULT
 
436
     */
 
437
    pjsua_stun_use      mediaStunUse;
 
438
 
 
439
    /**
 
440
     * Enable ICE for the media transport.
 
441
     *
 
442
     * Default: False
 
443
     */
 
444
    bool                iceEnabled;
 
445
 
 
446
    /**
 
447
     * Set the maximum number of ICE host candidates.
 
448
     *
 
449
     * Default: -1 (maximum not set)
 
450
     */
 
451
    int                 iceMaxHostCands;
 
452
 
 
453
    /**
 
454
     * Specify whether to use aggressive nomination.
 
455
     *
 
456
     * Default: True
 
457
     */
 
458
    bool                iceAggressiveNomination;
 
459
 
 
460
    /**
 
461
     * For controlling agent if it uses regular nomination, specify the delay
 
462
     * to perform nominated check (connectivity check with USE-CANDIDATE
 
463
     * attribute) after all components have a valid pair.
 
464
     *
 
465
     * Default value is PJ_ICE_NOMINATED_CHECK_DELAY.
 
466
     */
 
467
    unsigned            iceNominatedCheckDelayMsec;
 
468
 
 
469
    /**
 
470
     * For a controlled agent, specify how long it wants to wait (in
 
471
     * milliseconds) for the controlling agent to complete sending
 
472
     * connectivity check with nominated flag set to true for all components
 
473
     * after the controlled agent has found that all connectivity checks in
 
474
     * its checklist have been completed and there is at least one successful
 
475
     * (but not nominated) check for every component.
 
476
     *
 
477
     * Default value for this option is
 
478
     * ICE_CONTROLLED_AGENT_WAIT_NOMINATION_TIMEOUT. Specify -1 to disable
 
479
     * this timer.
 
480
     */
 
481
    int                 iceWaitNominationTimeoutMsec;
 
482
 
 
483
    /**
 
484
     * Disable RTCP component.
 
485
     *
 
486
     * Default: False
 
487
     */
 
488
    bool                iceNoRtcp;
 
489
 
 
490
    /**
 
491
     * Always send re-INVITE/UPDATE after ICE negotiation regardless of whether
 
492
     * the default ICE transport address is changed or not. When this is set
 
493
     * to False, re-INVITE/UPDATE will be sent only when the default ICE
 
494
     * transport address is changed.
 
495
     *
 
496
     * Default: yes
 
497
     */
 
498
    bool                iceAlwaysUpdate;
 
499
 
 
500
    /**
 
501
     * Enable TURN candidate in ICE.
 
502
     */
 
503
    bool                turnEnabled;
 
504
 
 
505
    /**
 
506
     * Specify TURN domain name or host name, in in "DOMAIN:PORT" or
 
507
     * "HOST:PORT" format.
 
508
     */
 
509
    string              turnServer;
 
510
 
 
511
    /**
 
512
     * Specify the connection type to be used to the TURN server. Valid
 
513
     * values are PJ_TURN_TP_UDP or PJ_TURN_TP_TCP.
 
514
     *
 
515
     * Default: PJ_TURN_TP_UDP
 
516
     */
 
517
    pj_turn_tp_type     turnConnType;
 
518
 
 
519
    /**
 
520
     * Specify the username to authenticate with the TURN server.
 
521
     */
 
522
    string              turnUserName;
 
523
 
 
524
    /**
 
525
     * Specify the type of password. Currently this must be zero to
 
526
     * indicate plain-text password will be used in the password.
 
527
     */
 
528
    int                 turnPasswordType;
 
529
 
 
530
    /**
 
531
     * Specify the password to authenticate with the TURN server.
 
532
     */
 
533
    string              turnPassword;
 
534
 
 
535
    /**
 
536
     * This option is used to update the transport address and the Contact
 
537
     * header of REGISTER request. When this option is  enabled, the library
 
538
     * will keep track of the public IP address from the response of REGISTER
 
539
     * request. Once it detects that the address has changed, it will
 
540
     * unregister current Contact, update the Contact with transport address
 
541
     * learned from Via header, and register a new Contact to the registrar.
 
542
     * This will also update the public name of UDP transport if STUN is
 
543
     * configured.
 
544
     *
 
545
     * See also contactRewriteMethod field.
 
546
     *
 
547
     * Default: TRUE
 
548
     */
 
549
    int                 contactRewriteUse;
 
550
 
 
551
    /**
 
552
     * Specify how Contact update will be done with the registration, if
 
553
     * \a contactRewriteEnabled is enabled. The value is bitmask combination of
 
554
     * \a pjsua_contact_rewrite_method. See also pjsua_contact_rewrite_method.
 
555
     *
 
556
     * Value PJSUA_CONTACT_REWRITE_UNREGISTER(1) is the legacy behavior.
 
557
     *
 
558
     * Default value: PJSUA_CONTACT_REWRITE_METHOD
 
559
     *   (PJSUA_CONTACT_REWRITE_NO_UNREG | PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE)
 
560
     */
 
561
    int                 contactRewriteMethod;
 
562
 
 
563
    /**
 
564
     * This option is used to overwrite the "sent-by" field of the Via header
 
565
     * for outgoing messages with the same interface address as the one in
 
566
     * the REGISTER request, as long as the request uses the same transport
 
567
     * instance as the previous REGISTER request.
 
568
     *
 
569
     * Default: TRUE
 
570
     */
 
571
    int                 viaRewriteUse;
 
572
 
 
573
    /**
 
574
     * This option controls whether the IP address in SDP should be replaced
 
575
     * with the IP address found in Via header of the REGISTER response, ONLY
 
576
     * when STUN and ICE are not used. If the value is FALSE (the original
 
577
     * behavior), then the local IP address will be used. If TRUE, and when
 
578
     * STUN and ICE are disabled, then the IP address found in registration
 
579
     * response will be used.
 
580
     *
 
581
     * Default: PJ_FALSE (no)
 
582
     */
 
583
    int                 sdpNatRewriteUse;
 
584
 
 
585
    /**
 
586
     * Control the use of SIP outbound feature. SIP outbound is described in
 
587
     * RFC 5626 to enable proxies or registrar to send inbound requests back
 
588
     * to UA using the same connection initiated by the UA for its
 
589
     * registration. This feature is highly useful in NAT-ed deployemtns,
 
590
     * hence it is enabled by default.
 
591
     *
 
592
     * Note: currently SIP outbound can only be used with TCP and TLS
 
593
     * transports. If UDP is used for the registration, the SIP outbound
 
594
     * feature will be silently ignored for the account.
 
595
     *
 
596
     * Default: TRUE
 
597
     */
 
598
    int                 sipOutboundUse;
 
599
 
 
600
    /**
 
601
     * Specify SIP outbound (RFC 5626) instance ID to be used by this
 
602
     * account. If empty, an instance ID will be generated based on
 
603
     * the hostname of this agent. If application specifies this parameter, the
 
604
     * value will look like "<urn:uuid:00000000-0000-1000-8000-AABBCCDDEEFF>"
 
605
     * without the double-quotes.
 
606
     *
 
607
     * Default: empty
 
608
     */
 
609
    string              sipOutboundInstanceId;
 
610
 
 
611
    /**
 
612
     * Specify SIP outbound (RFC 5626) registration ID. The default value
 
613
     * is empty, which would cause the library to automatically generate
 
614
     * a suitable value.
 
615
     *
 
616
     * Default: empty
 
617
     */
 
618
    string              sipOutboundRegId;
 
619
 
 
620
    /**
 
621
     * Set the interval for periodic keep-alive transmission for this account.
 
622
     * If this value is zero, keep-alive will be disabled for this account.
 
623
     * The keep-alive transmission will be sent to the registrar's address,
 
624
     * after successful registration.
 
625
     *
 
626
     * Default: 15 (seconds)
 
627
     */
 
628
    unsigned            udpKaIntervalSec;
 
629
 
 
630
    /**
 
631
     * Specify the data to be transmitted as keep-alive packets.
 
632
     *
 
633
     * Default: CR-LF
 
634
     */
 
635
    string              udpKaData;
 
636
 
 
637
public:
 
638
    /**
 
639
     * Read this object from a container node.
 
640
     *
 
641
     * @param node              Container to read values from.
 
642
     */
 
643
    virtual void readObject(const ContainerNode &node) throw(Error);
 
644
 
 
645
    /**
 
646
     * Write this object to a container node.
 
647
     *
 
648
     * @param node              Container to write values to.
 
649
     */
 
650
    virtual void writeObject(ContainerNode &node) const throw(Error);
 
651
};
 
652
 
 
653
/**
 
654
 * Account media config (applicable for both audio and video). This will be
 
655
 * specified in AccountConfig.
 
656
 */
 
657
struct AccountMediaConfig : public PersistentObject
 
658
{
 
659
    /**
 
660
     * Media transport (RTP) configuration.
 
661
     */
 
662
    TransportConfig     transportConfig;
 
663
 
 
664
    /**
 
665
     * If remote sends SDP answer containing more than one format or codec in
 
666
     * the media line, send re-INVITE or UPDATE with just one codec to lock
 
667
     * which codec to use.
 
668
     *
 
669
     * Default: True (Yes).
 
670
     */
 
671
    bool                lockCodecEnabled;
 
672
 
 
673
    /**
 
674
     * Specify whether stream keep-alive and NAT hole punching with
 
675
     * non-codec-VAD mechanism (see PJMEDIA_STREAM_ENABLE_KA) is enabled
 
676
     * for this account.
 
677
     *
 
678
     * Default: False
 
679
     */
 
680
    bool                streamKaEnabled;
 
681
 
 
682
    /**
 
683
     * Specify whether secure media transport should be used for this account.
 
684
     * Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and
 
685
     * PJMEDIA_SRTP_MANDATORY.
 
686
     *
 
687
     * Default: PJSUA_DEFAULT_USE_SRTP
 
688
     */
 
689
    pjmedia_srtp_use    srtpUse;
 
690
 
 
691
    /**
 
692
     * Specify whether SRTP requires secure signaling to be used. This option
 
693
     * is only used when \a use_srtp option above is non-zero.
 
694
     *
 
695
     * Valid values are:
 
696
     *  0: SRTP does not require secure signaling
 
697
     *  1: SRTP requires secure transport such as TLS
 
698
     *  2: SRTP requires secure end-to-end transport (SIPS)
 
699
     *
 
700
     * Default: PJSUA_DEFAULT_SRTP_SECURE_SIGNALING
 
701
     */
 
702
    int                 srtpSecureSignaling;
 
703
 
 
704
    /**
 
705
     * Specify whether IPv6 should be used on media. Default is not used.
 
706
     */
 
707
    pjsua_ipv6_use      ipv6Use;
 
708
 
 
709
public:
 
710
    /**
 
711
     * Read this object from a container node.
 
712
     *
 
713
     * @param node              Container to read values from.
 
714
     */
 
715
    virtual void readObject(const ContainerNode &node) throw(Error);
 
716
 
 
717
    /**
 
718
     * Write this object to a container node.
 
719
     *
 
720
     * @param node              Container to write values to.
 
721
     */
 
722
    virtual void writeObject(ContainerNode &node) const throw(Error);
 
723
};
 
724
 
 
725
/**
 
726
 * Account video config. This will be specified in AccountConfig.
 
727
 */
 
728
struct AccountVideoConfig : public PersistentObject
 
729
{
 
730
    /**
 
731
     * Specify whether incoming video should be shown to screen by default.
 
732
     * This applies to incoming call (INVITE), incoming re-INVITE, and
 
733
     * incoming UPDATE requests.
 
734
     *
 
735
     * Regardless of this setting, application can detect incoming video
 
736
     * by implementing \a on_call_media_state() callback and enumerating
 
737
     * the media stream(s) with pjsua_call_get_info(). Once incoming
 
738
     * video is recognised, application may retrieve the window associated
 
739
     * with the incoming video and show or hide it with
 
740
     * pjsua_vid_win_set_show().
 
741
     *
 
742
     * Default: False
 
743
     */
 
744
    bool                        autoShowIncoming;
 
745
 
 
746
    /**
 
747
     * Specify whether outgoing video should be activated by default when
 
748
     * making outgoing calls and/or when incoming video is detected. This
 
749
     * applies to incoming and outgoing calls, incoming re-INVITE, and
 
750
     * incoming UPDATE. If the setting is non-zero, outgoing video
 
751
     * transmission will be started as soon as response to these requests
 
752
     * is sent (or received).
 
753
     *
 
754
     * Regardless of the value of this setting, application can start and
 
755
     * stop outgoing video transmission with pjsua_call_set_vid_strm().
 
756
     *
 
757
     * Default: False
 
758
     */
 
759
    bool                        autoTransmitOutgoing;
 
760
 
 
761
    /**
 
762
     * Specify video window's flags. The value is a bitmask combination of
 
763
     * pjmedia_vid_dev_wnd_flag.
 
764
     *
 
765
     * Default: 0
 
766
     */
 
767
    unsigned                    windowFlags;
 
768
 
 
769
    /**
 
770
     * Specify the default capture device to be used by this account. If
 
771
     * vidOutAutoTransmit is enabled, this device will be used for
 
772
     * capturing video.
 
773
     *
 
774
     * Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV
 
775
     */
 
776
    pjmedia_vid_dev_index       defaultCaptureDevice;
 
777
 
 
778
    /**
 
779
     * Specify the default rendering device to be used by this account.
 
780
     *
 
781
     * Default: PJMEDIA_VID_DEFAULT_RENDER_DEV
 
782
     */
 
783
    pjmedia_vid_dev_index       defaultRenderDevice;
 
784
 
 
785
    /**
 
786
     * Rate control method.
 
787
     *
 
788
     * Default: PJMEDIA_VID_STREAM_RC_SIMPLE_BLOCKING.
 
789
     */
 
790
    pjmedia_vid_stream_rc_method rateControlMethod;
 
791
 
 
792
    /**
 
793
     * Upstream/outgoing bandwidth. If this is set to zero, the video stream
 
794
     * will use codec maximum bitrate setting.
 
795
     *
 
796
     * Default: 0 (follow codec maximum bitrate).
 
797
     */
 
798
    unsigned                    rateControlBandwidth;
 
799
 
 
800
public:
 
801
    /**
 
802
     * Read this object from a container node.
 
803
     *
 
804
     * @param node              Container to read values from.
 
805
     */
 
806
    virtual void readObject(const ContainerNode &node) throw(Error);
 
807
 
 
808
    /**
 
809
     * Write this object to a container node.
 
810
     *
 
811
     * @param node              Container to write values to.
 
812
     */
 
813
    virtual void writeObject(ContainerNode &node) const throw(Error);
 
814
};
 
815
 
 
816
/**
 
817
 * Account configuration.
 
818
 */
 
819
struct AccountConfig : public PersistentObject
 
820
{
 
821
    /**
 
822
     * Account priority, which is used to control the order of matching
 
823
     * incoming/outgoing requests. The higher the number means the higher
 
824
     * the priority is, and the account will be matched first.
 
825
     */
 
826
    int                 priority;
 
827
 
 
828
    /**
 
829
     * The Address of Record or AOR, that is full SIP URL that identifies the
 
830
     * account. The value can take name address or URL format, and will look
 
831
     * something like "sip:account@serviceprovider".
 
832
     *
 
833
     * This field is mandatory.
 
834
     */
 
835
    string              idUri;
 
836
 
 
837
    /**
 
838
     * Registration settings.
 
839
     */
 
840
    AccountRegConfig    regConfig;
 
841
 
 
842
    /**
 
843
     * SIP settings.
 
844
     */
 
845
    AccountSipConfig    sipConfig;
 
846
 
 
847
    /**
 
848
     * Call settings.
 
849
     */
 
850
    AccountCallConfig   callConfig;
 
851
 
 
852
    /**
 
853
     * Presence settings.
 
854
     */
 
855
    AccountPresConfig   presConfig;
 
856
 
 
857
    /**
 
858
     * MWI (Message Waiting Indication) settings.
 
859
     */
 
860
    AccountMwiConfig    mwiConfig;
 
861
 
 
862
    /**
 
863
     * NAT settings.
 
864
     */
 
865
    AccountNatConfig    natConfig;
 
866
 
 
867
    /**
 
868
     * Media settings (applicable for both audio and video).
 
869
     */
 
870
    AccountMediaConfig  mediaConfig;
 
871
 
 
872
    /**
 
873
     * Video settings.
 
874
     */
 
875
    AccountVideoConfig  videoConfig;
 
876
 
 
877
public:
 
878
    /**
 
879
     * Default constructor will initialize with default values.
 
880
     */
 
881
    AccountConfig();
 
882
 
 
883
    /**
 
884
     * This will return a temporary pjsua_acc_config instance, which contents
 
885
     * are only valid as long as this AccountConfig structure remains valid
 
886
     * AND no modifications are done to it AND no further toPj() function call
 
887
     * is made. Any call to toPj() function will invalidate the content of
 
888
     * temporary pjsua_acc_config that was returned by the previous call.
 
889
     */
 
890
    void toPj(pjsua_acc_config &cfg) const;
 
891
 
 
892
    /**
 
893
     * Initialize from pjsip.
 
894
     */
 
895
    void fromPj(const pjsua_acc_config &prm, const pjsua_media_config *mcfg);
 
896
 
 
897
    /**
 
898
     * Read this object from a container node.
 
899
     *
 
900
     * @param node              Container to read values from.
 
901
     */
 
902
    virtual void readObject(const ContainerNode &node) throw(Error);
 
903
 
 
904
    /**
 
905
     * Write this object to a container node.
 
906
     *
 
907
     * @param node              Container to write values to.
 
908
     */
 
909
    virtual void writeObject(ContainerNode &node) const throw(Error);
 
910
};
 
911
 
 
912
 
 
913
/**
 
914
 * Account information. Application can query the account information
 
915
 * by calling Account::getInfo().
 
916
 */
 
917
struct AccountInfo
 
918
{
 
919
    /**
 
920
     * The account ID.
 
921
     */
 
922
    pjsua_acc_id        id;
 
923
 
 
924
    /**
 
925
     * Flag to indicate whether this is the default account.
 
926
     */
 
927
    bool                isDefault;
 
928
 
 
929
    /**
 
930
     * Account URI
 
931
     */
 
932
    string              uri;
 
933
 
 
934
    /**
 
935
     * Flag to tell whether this account has registration setting
 
936
     * (reg_uri is not empty).
 
937
     */
 
938
    bool                regIsConfigured;
 
939
 
 
940
    /**
 
941
     * Flag to tell whether this account is currently registered
 
942
     * (has active registration session).
 
943
     */
 
944
    bool                regIsActive;
 
945
 
 
946
    /**
 
947
     * An up to date expiration interval for account registration session.
 
948
     */
 
949
    int                 regExpiresSec;
 
950
 
 
951
    /**
 
952
     * Last registration status code. If status code is zero, the account
 
953
     * is currently not registered. Any other value indicates the SIP
 
954
     * status code of the registration.
 
955
     */
 
956
    pjsip_status_code   regStatus;
 
957
 
 
958
    /**
 
959
     * String describing the registration status.
 
960
     */
 
961
    string              regStatusText;
 
962
 
 
963
    /**
 
964
     * Last registration error code. When the status field contains a SIP
 
965
     * status code that indicates a registration failure, last registration
 
966
     * error code contains the error code that causes the failure. In any
 
967
     * other case, its value is zero.
 
968
     */
 
969
    pj_status_t         regLastErr;
 
970
 
 
971
    /**
 
972
     * Presence online status for this account.
 
973
     */
 
974
    bool                onlineStatus;
 
975
 
 
976
    /**
 
977
     * Presence online status text.
 
978
     */
 
979
    string              onlineStatusText;
 
980
 
 
981
public:
 
982
    /** Import from pjsip data */
 
983
    void fromPj(const pjsua_acc_info &pai);
 
984
};
 
985
 
 
986
/**
 
987
 * This structure contains parameters for onIncomingCall() account callback.
 
988
 */
 
989
struct OnIncomingCallParam
 
990
{
 
991
    /**
 
992
     * The library call ID allocated for the new call.
 
993
     */
 
994
    int                 callId;
 
995
 
 
996
    /**
 
997
     * The incoming INVITE request.
 
998
     */
 
999
    SipRxData           rdata;
 
1000
};
 
1001
 
 
1002
/**
 
1003
 * This structure contains parameters for onRegStarted() account callback.
 
1004
 */
 
1005
struct OnRegStartedParam
 
1006
{
 
1007
    /**
 
1008
     * True for registration and False for unregistration.
 
1009
     */
 
1010
    bool renew;
 
1011
};
 
1012
 
 
1013
/**
 
1014
 * This structure contains parameters for onRegState() account callback.
 
1015
 */
 
1016
struct OnRegStateParam
 
1017
{
 
1018
    /**
 
1019
     * Registration operation status.
 
1020
     */
 
1021
    pj_status_t         status;
 
1022
 
 
1023
    /**
 
1024
     * SIP status code received.
 
1025
     */
 
1026
    pjsip_status_code   code;
 
1027
 
 
1028
    /**
 
1029
     * SIP reason phrase received.
 
1030
     */
 
1031
    string              reason;
 
1032
 
 
1033
    /**
 
1034
     * The incoming message.
 
1035
     */
 
1036
    SipRxData           rdata;
 
1037
 
 
1038
    /**
 
1039
     * Next expiration interval.
 
1040
     */
 
1041
    int                 expiration;
 
1042
};
 
1043
 
 
1044
/**
 
1045
 * This structure contains parameters for onIncomingSubscribe() callback.
 
1046
 */
 
1047
struct OnIncomingSubscribeParam
 
1048
{
 
1049
    /**
 
1050
     * Server presence subscription instance. If application delays
 
1051
     * the acceptance of the request, it will need to specify this object
 
1052
     * when calling Account::presNotify().
 
1053
     */
 
1054
    void               *srvPres;
 
1055
 
 
1056
    /**
 
1057
     *  Sender URI.
 
1058
     */
 
1059
    string              fromUri;
 
1060
 
 
1061
    /**
 
1062
     * The incoming message.
 
1063
     */
 
1064
    SipRxData           rdata;
 
1065
 
 
1066
    /**
 
1067
     * The status code to respond to the request. The default value is 200.
 
1068
     * Application may set this to other final status code to accept or
 
1069
     * reject the request.
 
1070
     */
 
1071
    pjsip_status_code   code;
 
1072
 
 
1073
    /**
 
1074
     * The reason phrase to respond to the request.
 
1075
     */
 
1076
    string              reason;
 
1077
 
 
1078
    /**
 
1079
     * Additional data to be sent with the response, if any.
 
1080
     */
 
1081
    SipTxOption         txOption;
 
1082
};
 
1083
 
 
1084
/**
 
1085
 * Parameters for onInstantMessage() account callback.
 
1086
 */
 
1087
struct OnInstantMessageParam
 
1088
{
 
1089
    /**
 
1090
     * Sender From URI.
 
1091
     */
 
1092
    string              fromUri;
 
1093
 
 
1094
    /**
 
1095
     * To URI of the request.
 
1096
     */
 
1097
    string              toUri;
 
1098
 
 
1099
    /**
 
1100
     * Contact URI of the sender.
 
1101
     */
 
1102
    string              contactUri;
 
1103
 
 
1104
    /**
 
1105
     * MIME type of the message body.
 
1106
     */
 
1107
    string              contentType;
 
1108
 
 
1109
    /**
 
1110
     * The message body.
 
1111
     */
 
1112
    string              msgBody;
 
1113
 
 
1114
    /**
 
1115
     * The whole message.
 
1116
     */
 
1117
    SipRxData           rdata;
 
1118
};
 
1119
 
 
1120
/**
 
1121
 * Parameters for onInstantMessageStatus() account callback.
 
1122
 */
 
1123
struct OnInstantMessageStatusParam
 
1124
{
 
1125
    /**
 
1126
     * Token or a user data that was associated with the pager
 
1127
     * transmission.
 
1128
     */
 
1129
    Token               userData;
 
1130
 
 
1131
    /**
 
1132
     * Destination URI.
 
1133
     */
 
1134
    string              toUri;
 
1135
 
 
1136
    /**
 
1137
     * The message body.
 
1138
     */
 
1139
    string              msgBody;
 
1140
 
 
1141
    /**
 
1142
     * The SIP status code of the transaction.
 
1143
     */
 
1144
    pjsip_status_code   code;
 
1145
 
 
1146
    /**
 
1147
     * The reason phrase of the transaction.
 
1148
     */
 
1149
    string              reason;
 
1150
 
 
1151
    /**
 
1152
     * The incoming response that causes this callback to be called.
 
1153
     * If the transaction fails because of time out or transport error,
 
1154
     * the content will be empty.
 
1155
     */
 
1156
    SipRxData           rdata;
 
1157
};
 
1158
 
 
1159
/**
 
1160
 * Parameters for onTypingIndication() account callback.
 
1161
 */
 
1162
struct OnTypingIndicationParam
 
1163
{
 
1164
    /**
 
1165
     * Sender/From URI.
 
1166
     */
 
1167
    string              fromUri;
 
1168
 
 
1169
    /**
 
1170
     * To URI.
 
1171
     */
 
1172
    string              toUri;
 
1173
 
 
1174
    /**
 
1175
     * The Contact URI.
 
1176
     */
 
1177
    string              contactUri;
 
1178
 
 
1179
    /**
 
1180
     * Boolean to indicate if sender is typing.
 
1181
     */
 
1182
    bool                isTyping;
 
1183
 
 
1184
    /**
 
1185
     * The whole message buffer.
 
1186
     */
 
1187
    SipRxData           rdata;
 
1188
};
 
1189
 
 
1190
/**
 
1191
 * Parameters for onMwiInfo() account callback.
 
1192
 */
 
1193
struct OnMwiInfoParam
 
1194
{
 
1195
    /**
 
1196
     * MWI subscription state.
 
1197
     */
 
1198
    pjsip_evsub_state   state;
 
1199
 
 
1200
    /**
 
1201
     * The whole message buffer.
 
1202
     */
 
1203
    SipRxData           rdata;
 
1204
};
 
1205
 
 
1206
/**
 
1207
 * Parameters for presNotify() account method.
 
1208
 */
 
1209
struct PresNotifyParam
 
1210
{
 
1211
    /**
 
1212
     * Server presence subscription instance.
 
1213
     */
 
1214
    void               *srvPres;
 
1215
 
 
1216
    /**
 
1217
     * Server presence subscription state to set.
 
1218
     */
 
1219
    pjsip_evsub_state   state;
 
1220
    
 
1221
    /**
 
1222
     * Optionally specify the state string name, if state is not "active",
 
1223
     * "pending", or "terminated".
 
1224
     */
 
1225
    string              stateStr;
 
1226
 
 
1227
    /**
 
1228
     * If the new state is PJSIP_EVSUB_STATE_TERMINATED, optionally specify
 
1229
     * the termination reason.
 
1230
     */
 
1231
    string              reason;
 
1232
 
 
1233
    /**
 
1234
     * If the new state is PJSIP_EVSUB_STATE_TERMINATED, this specifies
 
1235
     * whether the NOTIFY request should contain message body containing
 
1236
     * account's presence information.
 
1237
     */
 
1238
    bool                withBody;
 
1239
 
 
1240
    /**
 
1241
     * Optional list of headers to be sent with the NOTIFY request.
 
1242
     */
 
1243
    SipTxOption         txOption;
 
1244
};
 
1245
 
 
1246
 
 
1247
/**
 
1248
 * Wrapper class for Buddy matching algo.
 
1249
 *
 
1250
 * Default algo is a simple substring lookup of search-token in the
 
1251
 * Buddy URIs, with case sensitive. Application can implement its own
 
1252
 * matching algo by overriding this class and specifying its instance
 
1253
 * in Account::findBuddy().
 
1254
 */
 
1255
class FindBuddyMatch
 
1256
{
 
1257
public:
 
1258
    /**
 
1259
     * Default algo implementation.
 
1260
     */
 
1261
    virtual bool match(const string &token, const Buddy &buddy)
 
1262
    {
 
1263
        BuddyInfo bi = buddy.getInfo();
 
1264
        return bi.uri.find(token) != string::npos;
 
1265
    }
 
1266
 
 
1267
    /**
 
1268
     * Destructor.
 
1269
     */
 
1270
    virtual ~FindBuddyMatch() {}
 
1271
};
 
1272
 
 
1273
 
 
1274
/**
 
1275
 * Account.
 
1276
 */
 
1277
class Account
 
1278
{
 
1279
public:
 
1280
    /**
 
1281
     * Constructor.
 
1282
     */
 
1283
    Account();
 
1284
 
 
1285
    /**
 
1286
     * Destructor. Note that if the account is deleted, it will also delete
 
1287
     * the corresponding account in the PJSUA-LIB.
 
1288
     */
 
1289
    virtual ~Account();
 
1290
 
 
1291
    /**
 
1292
     * Create the account.
 
1293
     *
 
1294
     * @param cfg               The account config.
 
1295
     * @param make_default      Make this the default account.
 
1296
     */
 
1297
    void create(const AccountConfig &cfg,
 
1298
                bool make_default=false) throw(Error);
 
1299
 
 
1300
    /**
 
1301
     * Modify the account to use the specified account configuration.
 
1302
     * Depending on the changes, this may cause unregistration or
 
1303
     * reregistration on the account.
 
1304
     *
 
1305
     * @param cfg               New account config to be applied to the
 
1306
     *                          account.
 
1307
     */
 
1308
    void modify(const AccountConfig &cfg) throw(Error);
 
1309
 
 
1310
    /**
 
1311
     * Check if this account is still valid.
 
1312
     *
 
1313
     * @return                  True if it is.
 
1314
     */
 
1315
    bool isValid() const;
 
1316
 
 
1317
    /**
 
1318
     * Set this as default account to be used when incoming and outgoing
 
1319
     * requests don't match any accounts.
 
1320
     *
 
1321
     * @return                  PJ_SUCCESS on success.
 
1322
     */
 
1323
    void setDefault() throw(Error);
 
1324
 
 
1325
    /**
 
1326
     * Check if this account is the default account. Default account will be
 
1327
     * used for incoming and outgoing requests that don't match any other
 
1328
     * accounts.
 
1329
     *
 
1330
     * @return                  True if this is the default account.
 
1331
     */
 
1332
    bool isDefault() const;
 
1333
 
 
1334
    /**
 
1335
     * Get PJSUA-LIB account ID or index associated with this account.
 
1336
     *
 
1337
     * @return                  Integer greater than or equal to zero.
 
1338
     */
 
1339
    int getId() const;
 
1340
 
 
1341
    /**
 
1342
     * Get the Account class for the specified account Id.
 
1343
     *
 
1344
     * @param acc_id            The account ID to lookup
 
1345
     *
 
1346
     * @return                  The Account instance or NULL if not found.
 
1347
     */
 
1348
    static Account *lookup(int acc_id);
 
1349
 
 
1350
    /**
 
1351
     * Get account info.
 
1352
     *
 
1353
     * @return                  Account info.
 
1354
     */
 
1355
    AccountInfo getInfo() const throw(Error);
 
1356
 
 
1357
    /**
 
1358
     * Update registration or perform unregistration. Application normally
 
1359
     * only needs to call this function if it wants to manually update the
 
1360
     * registration or to unregister from the server.
 
1361
     *
 
1362
     * @param renew             If False, this will start unregistration
 
1363
     *                          process.
 
1364
     */
 
1365
    void setRegistration(bool renew) throw(Error);
 
1366
 
 
1367
    /**
 
1368
     * Set or modify account's presence online status to be advertised to
 
1369
     * remote/presence subscribers. This would trigger the sending of
 
1370
     * outgoing NOTIFY request if there are server side presence subscription
 
1371
     * for this account, and/or outgoing PUBLISH if presence publication is
 
1372
     * enabled for this account.
 
1373
     *
 
1374
     * @param pres_st           Presence online status.
 
1375
     */
 
1376
    void setOnlineStatus(const PresenceStatus &pres_st) throw(Error);
 
1377
 
 
1378
    /**
 
1379
     * Lock/bind this account to a specific transport/listener. Normally
 
1380
     * application shouldn't need to do this, as transports will be selected
 
1381
     * automatically by the library according to the destination.
 
1382
     *
 
1383
     * When account is locked/bound to a specific transport, all outgoing
 
1384
     * requests from this account will use the specified transport (this
 
1385
     * includes SIP registration, dialog (call and event subscription), and
 
1386
     * out-of-dialog requests such as MESSAGE).
 
1387
     *
 
1388
     * Note that transport id may be specified in AccountConfig too.
 
1389
     *
 
1390
     * @param tp_id             The transport ID.
 
1391
     */
 
1392
    void setTransport(TransportId tp_id) throw(Error);
 
1393
 
 
1394
    /**
 
1395
     * Send NOTIFY to inform account presence status or to terminate server
 
1396
     * side presence subscription. If application wants to reject the incoming
 
1397
     * request, it should set the param \a PresNotifyParam.state to
 
1398
     * PJSIP_EVSUB_STATE_TERMINATED.
 
1399
     *
 
1400
     * @param prm               The sending NOTIFY parameter.
 
1401
     */
 
1402
    void presNotify(const PresNotifyParam &prm) throw(Error);
 
1403
    
 
1404
    /**
 
1405
     * Enumerate all buddies of the account.
 
1406
     *
 
1407
     * @return                  The buddy list.
 
1408
     */
 
1409
    const BuddyVector& enumBuddies() const throw(Error);
 
1410
 
 
1411
    /**
 
1412
     * Find a buddy in the buddy list with the specified URI. 
 
1413
     *
 
1414
     * Exception: if buddy is not found, PJ_ENOTFOUND will be thrown.
 
1415
     *
 
1416
     * @param uri               The buddy URI.
 
1417
     * @param buddy_match       The buddy match algo.
 
1418
     *
 
1419
     * @return                  The pointer to buddy.
 
1420
     */
 
1421
    Buddy* findBuddy(string uri, FindBuddyMatch *buddy_match = NULL) const
 
1422
                    throw(Error);
 
1423
 
 
1424
    /**
 
1425
     * An internal function to add a Buddy to Account buddy list.
 
1426
     * This function must never be used by application.
 
1427
     */
 
1428
    void addBuddy(Buddy *buddy);
 
1429
 
 
1430
    /**
 
1431
     * An internal function to remove a Buddy from Account buddy list.
 
1432
     * This function must never be used by application.
 
1433
     */
 
1434
    void removeBuddy(Buddy *buddy);
 
1435
 
 
1436
public:
 
1437
    /*
 
1438
     * Callbacks
 
1439
     */
 
1440
    /**
 
1441
     * Notify application on incoming call.
 
1442
     *
 
1443
     * @param prm       Callback parameter.
 
1444
     */
 
1445
    virtual void onIncomingCall(OnIncomingCallParam &prm)
 
1446
    { PJ_UNUSED_ARG(prm); }
 
1447
 
 
1448
    /**
 
1449
     * Notify application when registration or unregistration has been
 
1450
     * initiated. Note that this only notifies the initial registration
 
1451
     * and unregistration. Once registration session is active, subsequent
 
1452
     * refresh will not cause this callback to be called.
 
1453
     *
 
1454
     * @param prm           Callback parameter.
 
1455
     */
 
1456
    virtual void onRegStarted(OnRegStartedParam &prm)
 
1457
    { PJ_UNUSED_ARG(prm); }
 
1458
 
 
1459
    /**
 
1460
     * Notify application when registration status has changed.
 
1461
     * Application may then query the account info to get the
 
1462
     * registration details.
 
1463
     *
 
1464
     * @param prm           Callback parameter.
 
1465
     */
 
1466
    virtual void onRegState(OnRegStateParam &prm)
 
1467
    { PJ_UNUSED_ARG(prm); }
 
1468
 
 
1469
    /**
 
1470
     * Notification when incoming SUBSCRIBE request is received. Application
 
1471
     * may use this callback to authorize the incoming subscribe request
 
1472
     * (e.g. ask user permission if the request should be granted).
 
1473
     *
 
1474
     * If this callback is not implemented, all incoming presence subscription
 
1475
     * requests will be accepted.
 
1476
     *
 
1477
     * If this callback is implemented, application has several choices on
 
1478
     * what to do with the incoming request:
 
1479
     *  - it may reject the request immediately by specifying non-200 class
 
1480
     *    final response in the IncomingSubscribeParam.code parameter.
 
1481
     *  - it may immediately accept the request by specifying 200 as the
 
1482
     *    IncomingSubscribeParam.code parameter. This is the default value if
 
1483
     *    application doesn't set any value to the IncomingSubscribeParam.code
 
1484
     *    parameter. In this case, the library will automatically send NOTIFY
 
1485
     *    request upon returning from this callback.
 
1486
     *  - it may delay the processing of the request, for example to request
 
1487
     *    user permission whether to accept or reject the request. In this
 
1488
     *    case, the application MUST set the IncomingSubscribeParam.code
 
1489
     *    argument to 202, then IMMEDIATELY calls presNotify() with
 
1490
     *    state PJSIP_EVSUB_STATE_PENDING and later calls presNotify()
 
1491
     *    again to accept or reject the subscription request.
 
1492
     *
 
1493
     * Any IncomingSubscribeParam.code other than 200 and 202 will be treated
 
1494
     * as 200.
 
1495
     *
 
1496
     * Application MUST return from this callback immediately (e.g. it must
 
1497
     * not block in this callback while waiting for user confirmation).
 
1498
     *
 
1499
     * @param prm           Callback parameter.
 
1500
     */
 
1501
    virtual void onIncomingSubscribe(OnIncomingSubscribeParam &prm)
 
1502
    { PJ_UNUSED_ARG(prm); }
 
1503
 
 
1504
    /**
 
1505
     * Notify application on incoming instant message or pager (i.e. MESSAGE
 
1506
     * request) that was received outside call context.
 
1507
     *
 
1508
     * @param prm           Callback parameter.
 
1509
     */
 
1510
    virtual void onInstantMessage(OnInstantMessageParam &prm)
 
1511
    { PJ_UNUSED_ARG(prm); }
 
1512
 
 
1513
    /**
 
1514
     * Notify application about the delivery status of outgoing pager/instant
 
1515
     * message (i.e. MESSAGE) request.
 
1516
     *
 
1517
     * @param prm           Callback parameter.
 
1518
     */
 
1519
    virtual void onInstantMessageStatus(OnInstantMessageStatusParam &prm)
 
1520
    { PJ_UNUSED_ARG(prm); }
 
1521
 
 
1522
    /**
 
1523
     * Notify application about typing indication.
 
1524
     *
 
1525
     * @param prm           Callback parameter.
 
1526
     */
 
1527
    virtual void onTypingIndication(OnTypingIndicationParam &prm)
 
1528
    { PJ_UNUSED_ARG(prm); }
 
1529
 
 
1530
    /**
 
1531
     * Notification about MWI (Message Waiting Indication) status change.
 
1532
     * This callback can be called upon the status change of the
 
1533
     * SUBSCRIBE request (for example, 202/Accepted to SUBSCRIBE is received)
 
1534
     * or when a NOTIFY reqeust is received.
 
1535
     *
 
1536
     * @param prm           Callback parameter.
 
1537
     */
 
1538
    virtual void onMwiInfo(OnMwiInfoParam &prm)
 
1539
    { PJ_UNUSED_ARG(prm); }
 
1540
 
 
1541
protected:
 
1542
    friend class Endpoint;
 
1543
 
 
1544
private:
 
1545
    pjsua_acc_id         id;
 
1546
    string               tmpReason;     // for saving response's reason
 
1547
    BuddyVector          buddyList;
 
1548
};
 
1549
 
 
1550
/**
 
1551
 * @}  // PJSUA2_ACC
 
1552
 */
 
1553
 
 
1554
} // namespace pj
 
1555
 
 
1556
#endif  /* __PJSUA2_ACCOUNT_HPP__ */
 
1557