Accounts¶

Accounts provide identity (or identities) of the user who is currently using the application. An account has one SIP Uniform Resource Identifier (URI) associated with it. In SIP terms, this URI acts as Address of Record (AOR) of the person and is used as the From header in outgoing requests.

Account may or may not have client registration associated with it. An account is also associated with route set and some authentication credentials, which are used when sending SIP request messages using the account. An account also has presence status, which will be reported to remote peer when they subscribe to the account’s presence, or which is published to a presence server if presence publication is enabled for the account.

At least one account MUST be created in the application, since any outgoing requests require an account context. If no user association is required, application can create a userless account by calling Account.create(). A userless account identifies local endpoint instead of a particular user, and it corresponds to a particular transport ID.

Also one account must be set as the default account, which will be used as the account identity when pjsua fails to match incoming request with any accounts using the stricter matching rules.

Subclassing the Account class¶

To use the Account class, normally application SHOULD create its own subclass, in order to receive notifications for the account. For example:

class MyAccount : public Account
{
public:
    MyAccount() {}
    ~MyAccount() {}

    virtual void onRegState(OnRegStateParam &prm)
    {
        AccountInfo ai = getInfo();
        cout << (ai.regIsActive? "*** Register: code=" : "*** Unregister: code=")
             << prm.code << endl;
    }

    virtual void onIncomingCall(OnIncomingCallParam &iprm)
    {
        Call *call = new MyCall(*this, iprm.callId);

        // Just hangup for now
        CallOpParam op;
        op.statusCode = PJSIP_SC_DECLINE;
        call->hangup(op);

        // And delete the call
        delete call;
    }
};

In its subclass, application can implement the account callbacks, which is basically used to process events related to the account, such as:

the status of SIP registration
incoming calls
incoming presence subscription requests
incoming instant message not from buddy

Application needs to override the relevant callback methods in the derived class to handle these particular events.

If the events are not handled, default actions will be invoked:

incoming calls will not be handled
incoming presence subscription requests will be accepted
incoming instant messages from non-buddy will be ignored

Creating Userless Accounts¶

A userless account identifies a particular SIP endpoint rather than a particular user. Some other SIP softphones may call this peer-to-peer mode, which means that we are calling another computer via its address rather than calling a particular user ID. For example, we might identify ourselves as “sip:192.168.0.15” (a userless account) rather than, say, “sip:alice@pjsip.org”.

In the lower layer PJSUA-LIB API, a userless account is associated with a SIP transport, and is created with pjsua_acc_add_local() API. This concept has been deprecated in PJSUA2, and rather, a userless account is a “normal” account with a userless ID URI (e.g. “sip:192.168.0.15”) and without registration. Thus creating a userless account is exactly the same as creating “normal” account.

Creating Account¶

We need to configure AccountConfig and call Account.create() to create the account. At the very minimum, pjsua only requires the account’s ID, which is an URI to identify the account (or in SIP terms, it’s called Address of Record/AOR). Here’s a snippet:

AccountConfig acc_cfg;
acc_cfg.idUri = "sip:test1@pjsip.org";

MyAccount *acc = new MyAccount;
try {
    acc->create(acc_cfg);
} catch(Error& err) {
    cout << "Account creation error: " << err.info() << endl;
}

The account created above doesn’t do anything except to provide identity in the “From:” header for outgoing requests. The account will not register to SIP server or anything.

Typically you will want the account to authenticate and register to your SIP server so that you can receive incoming calls. To do that you will need to configure some more settings in your AccountConfig, something like this:

AccountConfig acc_cfg;
acc_cfg.idUri = "sip:test1@pjsip.org";
acc_cfg.regConfig.registrarUri = "sip:pjsip.org";
acc_cfg.sipConfig.authCreds.push_back( AuthCredInfo("digest", "*", "test1", 0, "secret1") );

MyAccount *acc = new MyAccount;
try {
    acc->create(acc_cfg);
} catch(Error& err) {
    cout << "Account creation error: " << err.info() << endl;
}

Account Configurations¶

There are many more settings that can be specified in AccountConfig, like:

AccountRegConfig, to specify registration settings, such as registrar server and retry interval.
AccountSipConfig, to specify SIP settings, such as credential information and proxy server.
AccountCallConfig, to specify call settings, such as whether reliable provisional response (SIP 100rel) is required.
AccountPresConfig, to specify presence settings, such as whether presence publication (PUBLISH) is enabled.
AccountMwiConfig, to specify MWI (Message Waiting Indication) settings.
AccountNatConfig, to specify NAT settings, such as whether STUN or ICE is used.
AccountMediaConfig, to specify media settings, such as Secure RTP (SRTP) related settings.
AccountVideoConfig, to specify video settings, such as default capture and render device.

Please see AccountConfig reference documentation for more info.

Account Operations¶

Some of the operations to the Account object:

manage registration
manage buddies/contacts
manage presence online status

Please see the reference documentation for Account for more info. Calls, presence, and buddy will be explained in later chapters.

Class Reference¶

Account¶

class Account

Account.

Public Functions

Account(): Constructor.

virtual ~Account()

Destructor. Note that if the account is deleted, it will also delete the corresponding account in the PJSUA-LIB.

If application implements a derived class, the derived class should call shutdown() in the beginning stage in its destructor, or alternatively application should call shutdown() before deleting the derived class instance. This is to avoid race condition between the derived class destructor and Account callbacks.

void create (const AccountConfig &cfg, bool make_default=false) PJSUA2_THROW(Error)

Create the account.

If application implements a derived class, the derived class should call shutdown() in the beginning stage in its destructor, or alternatively application should call shutdown() before deleting the derived class instance. This is to avoid race condition between the derived class destructor and Account callbacks.

Parameters

cfg – The account config.
make_default – Make this the default account.

void shutdown()

Shutdown the account. This will initiate unregistration if needed, and delete the corresponding account in the PJSUA-LIB.

Note that application must delete all Buddy instances belong to this account before shutting down the account.

If application implements a derived class, the derived class should call this method in the beginning stage in its destructor, or alternatively application should call this method before deleting the derived class instance. This is to avoid race condition between the derived class destructor and Account callbacks.

void modify (const AccountConfig &cfg) PJSUA2_THROW(Error)

Modify the account to use the specified account configuration. Depending on the changes, this may cause unregistration or reregistration on the account.

Parameters: cfg – New account config to be applied to the account.

bool isValid() const

Check if this account is still valid.

Returns: True if it is.

void setDefault () PJSUA2_THROW(Error): Set this as default account to be used when incoming and outgoing requests don’t match any accounts.

bool isDefault() const

Check if this account is the default account. Default account will be used for incoming and outgoing requests that don’t match any other accounts.

Returns: True if this is the default account.

int getId() const

Get PJSUA-LIB account ID or index associated with this account.

Returns: Integer greater than or equal to zero.

AccountInfo getInfo () const PJSUA2_THROW(Error)

Get account info.

Returns: Account info.

void setRegistration (bool renew) PJSUA2_THROW(Error)

Update registration or perform unregistration. Application normally only needs to call this function if it wants to manually update the registration or to unregister from the server.

Parameters: renew – If False, this will start unregistration process.

void setOnlineStatus (const PresenceStatus &pres_st) PJSUA2_THROW(Error)

Set or modify account’s presence online status to be advertised to remote/presence subscribers. This would trigger the sending of outgoing NOTIFY request if there are server side presence subscription for this account, and/or outgoing PUBLISH if presence publication is enabled for this account.

Parameters: pres_st – Presence online status.

void setTransport (TransportId tp_id) PJSUA2_THROW(Error)

Lock/bind this account to a specific transport/listener. Normally application shouldn’t need to do this, as transports will be selected automatically by the library according to the destination.

When account is locked/bound to a specific transport, all outgoing requests from this account will use the specified transport (this includes SIP registration, dialog (call and event subscription), and out-of-dialog requests such as MESSAGE).

Note that transport id may be specified in AccountConfig too.

Parameters: tp_id – The transport ID.

void presNotify (const PresNotifyParam &prm) PJSUA2_THROW(Error)

Send NOTIFY to inform account presence status or to terminate server side presence subscription. If application wants to reject the incoming request, it should set the param PresNotifyParam.state to PJSIP_EVSUB_STATE_TERMINATED.

Parameters: prm – The sending NOTIFY parameter.

const BuddyVector & enumBuddies () const PJSUA2_THROW(Error)

Warning: deprecated, use enumBuddies2() instead. This function is not safe in multithreaded environment.

Enumerate all buddies of the account.

Returns: The buddy list.

BuddyVector2 enumBuddies2 () const PJSUA2_THROW(Error)

Enumerate all buddies of the account.

Returns: The buddy list.

Buddy * findBuddy (string uri, FindBuddyMatch *buddy_match=NULL) const PJSUA2_THROW(Error)

Warning: deprecated, use findBuddy2 instead. This function is not safe in multithreaded environment.

Find a buddy in the buddy list with the specified URI.

Exception: if buddy is not found, PJ_ENOTFOUND will be thrown.

Parameters

uri – The buddy URI.
buddy_match – The buddy match algo.

Returns

The pointer to buddy.

Buddy findBuddy2 (string uri) const PJSUA2_THROW(Error)

Find a buddy in the buddy list with the specified URI.

Exception: if buddy is not found, PJ_ENOTFOUND will be thrown.

Parameters: uri – The buddy URI.
Returns: The pointer to buddy.

inline virtual void onIncomingCall(OnIncomingCallParam &prm)

Notify application on incoming call.

Parameters: prm – Callback parameter.

inline virtual void onRegStarted(OnRegStartedParam &prm)

Notify application when registration or unregistration has been initiated. Note that this only notifies the initial registration and unregistration. Once registration session is active, subsequent refresh will not cause this callback to be called.

Parameters: prm – Callback parameter.

inline virtual void onRegState(OnRegStateParam &prm)

Notify application when registration status has changed. Application may then query the account info to get the registration details.

Parameters: prm – Callback parameter.

inline virtual void onIncomingSubscribe(OnIncomingSubscribeParam &prm)

Notification when incoming SUBSCRIBE request is received. Application may use this callback to authorize the incoming subscribe request (e.g. ask user permission if the request should be granted).

If this callback is not implemented, all incoming presence subscription requests will be accepted.

If this callback is implemented, application has several choices on what to do with the incoming request:

it may reject the request immediately by specifying non-200 class final response in the IncomingSubscribeParam.code parameter.
it may immediately accept the request by specifying 200 as the IncomingSubscribeParam.code parameter. This is the default value if application doesn’t set any value to the IncomingSubscribeParam.code parameter. In this case, the library will automatically send NOTIFY request upon returning from this callback.
it may delay the processing of the request, for example to request user permission whether to accept or reject the request. In this case, the application MUST set the IncomingSubscribeParam.code argument to 202, then IMMEDIATELY calls presNotify() with state PJSIP_EVSUB_STATE_PENDING and later calls presNotify() again to accept or reject the subscription request.

Any IncomingSubscribeParam.code other than 200 and 202 will be treated as 200.

Application MUST return from this callback immediately (e.g. it must not block in this callback while waiting for user confirmation).

Parameters: prm – Callback parameter.

inline virtual void onInstantMessage(OnInstantMessageParam &prm)

Notify application on incoming instant message or pager (i.e. MESSAGE request) that was received outside call context.

Parameters: prm – Callback parameter.

inline virtual void onInstantMessageStatus(OnInstantMessageStatusParam &prm)

Notify application about the delivery status of outgoing pager/instant message (i.e. MESSAGE) request.

Parameters: prm – Callback parameter.

inline virtual void onTypingIndication(OnTypingIndicationParam &prm)

Notify application about typing indication.

Parameters: prm – Callback parameter.

inline virtual void onMwiInfo(OnMwiInfoParam &prm)

Notification about MWI (Message Waiting Indication) status change. This callback can be called upon the status change of the SUBSCRIBE request (for example, 202/Accepted to SUBSCRIBE is received) or when a NOTIFY reqeust is received.

Parameters: prm – Callback parameter.

Public Static Functions

static Account *lookup(int acc_id)

Get the Account class for the specified account Id.

Parameters: acc_id – The account ID to lookup
Returns: The Account instance or NULL if not found.

AccountInfo¶

struct AccountInfo

Account information. Application can query the account information by calling Account::getInfo().

Public Functions

inline AccountInfo(): Default constructor

void fromPj(const pjsua_acc_info &pai): Import from pjsip data

Public Members

pjsua_acc_id id: The account ID.

bool isDefault: Flag to indicate whether this is the default account.

string uri: Account URI

bool regIsConfigured: Flag to tell whether this account has registration setting (reg_uri is not empty).

bool regIsActive: Flag to tell whether this account is currently registered (has active registration session).

unsigned regExpiresSec: An up to date expiration interval for account registration session.

pjsip_status_code regStatus: Last registration status code. If status code is zero, the account is currently not registered. Any other value indicates the SIP status code of the registration.

string regStatusText: String describing the registration status.

pj_status_t regLastErr: Last registration error code. When the status field contains a SIP status code that indicates a registration failure, last registration error code contains the error code that causes the failure. In any other case, its value is zero.

bool onlineStatus: Presence online status for this account.

string onlineStatusText: Presence online status text.

Account Settings¶

AccountConfig¶

struct AccountConfig : public pj::PersistentObject

Account configuration.

Public Functions

AccountConfig(): Default constructor will initialize with default values.

void toPj(pjsua_acc_config &cfg) const: This will return a temporary pjsua_acc_config instance, which contents are only valid as long as this AccountConfig structure remains valid AND no modifications are done to it AND no further toPj() function call is made. Any call to toPj() function will invalidate the content of temporary pjsua_acc_config that was returned by the previous call.

void fromPj(const pjsua_acc_config &prm, const pjsua_media_config *mcfg): Initialize from pjsip.

virtual void readObject (const ContainerNode &node) PJSUA2_THROW(Error)

Read this object from a container node.

Parameters: node – Container to read values from.

virtual void writeObject (ContainerNode &node) const PJSUA2_THROW(Error)

Write this object to a container node.

Parameters: node – Container to write values to.

Public Members

int priority: Account priority, which is used to control the order of matching incoming/outgoing requests. The higher the number means the higher the priority is, and the account will be matched first.

string idUri

The Address of Record or AOR, that is full SIP URL that identifies the account. The value can take name address or URL format, and will look something like “sip:account@serviceprovider”.

This field is mandatory.

AccountRegConfig regConfig: Registration settings.

AccountSipConfig sipConfig: SIP settings.

AccountCallConfig callConfig: Call settings.

AccountPresConfig presConfig: Presence settings.

AccountMwiConfig mwiConfig: MWI (Message Waiting Indication) settings.

AccountNatConfig natConfig: NAT settings.

AccountMediaConfig mediaConfig: Media settings (applicable for both audio and video).

AccountVideoConfig videoConfig: Video settings.

AccountIpChangeConfig ipChangeConfig: IP Change settings.

AccoutRegConfig¶

struct AccountRegConfig : public pj::PersistentObject

Account registration config. This will be specified in AccountConfig.

Public Functions

virtual void readObject (const ContainerNode &node) PJSUA2_THROW(Error)

Read this object from a container node.

Parameters: node – Container to read values from.

virtual void writeObject (ContainerNode &node) const PJSUA2_THROW(Error)

Write this object to a container node.

Parameters: node – Container to write values to.

Public Members

string registrarUri

This is the URL to be put in the request URI for the registration, and will look something like “sip:serviceprovider”.

This field should be specified if registration is desired. If the value is empty, no account registration will be performed.

bool registerOnAdd

Specify whether the account should register as soon as it is added to the UA. Application can set this to PJ_FALSE and control the registration manually with pjsua_acc_set_registration().

Default: True

SipHeaderVector headers: The optional custom SIP headers to be put in the registration request.

string contactParams

Additional parameters that will be appended in the Contact header of the registration requests. This will be appended after AccountSipConfig.contactParams;

The parameters should be preceeded by semicolon, and all strings must be properly escaped. Example: “;my-param=X;another-param=Hi%20there”

unsigned timeoutSec: Optional interval for registration, in seconds. If the value is zero, default interval will be used (PJSUA_REG_INTERVAL, 300 seconds).

unsigned retryIntervalSec

Specify interval of auto registration retry upon registration failure (including caused by transport problem), in second. Set to 0 to disable auto re-registration. Note that if the registration retry occurs because of transport failure, the first retry will be done after firstRetryIntervalSec seconds instead. Also note that the interval will be randomized slightly by some seconds (specified in reg_retry_random_interval) to avoid all clients re-registering at the same time.

See also firstRetryIntervalSec and randomRetryIntervalSec settings.

Default: PJSUA_REG_RETRY_INTERVAL

unsigned firstRetryIntervalSec

This specifies the interval for the first registration retry. The registration retry is explained in retryIntervalSec. Note that the value here will also be randomized by some seconds (specified in reg_retry_random_interval) to avoid all clients re-registering at the same time.

See also retryIntervalSec and randomRetryIntervalSec settings.

Default: 0

unsigned randomRetryIntervalSec

This specifies maximum randomized value to be added/substracted to/from the registration retry interval specified in reg_retry_interval and reg_first_retry_interval, in second. This is useful to avoid all clients re-registering at the same time. For example, if the registration retry interval is set to 100 seconds and this is set to 10 seconds, the actual registration retry interval will be in the range of 90 to 110 seconds.

See also retryIntervalSec and firstRetryIntervalSec settings.

Default: 10

unsigned delayBeforeRefreshSec

Specify the number of seconds to refresh the client registration before the registration expires.

Default: PJSIP_REGISTER_CLIENT_DELAY_BEFORE_REFRESH, 5 seconds

bool dropCallsOnFail

Specify whether calls of the configured account should be dropped after registration failure and an attempt of re-registration has also failed.

Default: FALSE (disabled)

unsigned unregWaitMsec

Specify the maximum time to wait for unregistration requests to complete during library shutdown sequence.

Default: PJSUA_UNREG_TIMEOUT

unsigned proxyUse

Specify how the registration uses the outbound and account proxy settings. This controls if and what Route headers will appear in the REGISTER request of this account. The value is bitmask combination of PJSUA_REG_USE_OUTBOUND_PROXY and PJSUA_REG_USE_ACC_PROXY bits. If the value is set to 0, the REGISTER request will not use any proxy (i.e. it will not have any Route headers).

Default: 3 (PJSUA_REG_USE_OUTBOUND_PROXY | PJSUA_REG_USE_ACC_PROXY)

AccountSipConfig¶

struct AccountSipConfig : public pj::PersistentObject

Various SIP settings for the account. This will be specified in AccountConfig.

Public Functions

virtual void readObject (const ContainerNode &node) PJSUA2_THROW(Error)

Read this object from a container node.

Parameters: node – Container to read values from.

virtual void writeObject (ContainerNode &node) const PJSUA2_THROW(Error)

Write this object to a container node.

Parameters: node – Container to write values to.

Public Members

AuthCredInfoVector authCreds: Array of credentials. If registration is desired, normally there should be at least one credential specified, to successfully authenticate against the service provider. More credentials can be specified, for example when the requests are expected to be challenged by the proxies in the route set.

StringVector proxies: Array of proxy servers to visit for outgoing requests. Each of the entry is translated into one Route URI.

string contactForced: Optional URI to be put as Contact for this account. It is recommended that this field is left empty, so that the value will be calculated automatically based on the transport address.

string contactParams

Additional parameters that will be appended in the Contact header for this account. This will affect the Contact header in all SIP messages sent on behalf of this account, including but not limited to REGISTER, INVITE, and SUBCRIBE requests or responses.

The parameters should be preceeded by semicolon, and all strings must be properly escaped. Example: “;my-param=X;another-param=Hi%20there”

string contactUriParams

Additional URI parameters that will be appended in the Contact URI for this account. This will affect the Contact URI in all SIP messages sent on behalf of this account, including but not limited to REGISTER, INVITE, and SUBCRIBE requests or responses.

The parameters should be preceeded by semicolon, and all strings must be properly escaped. Example: “;my-param=X;another-param=Hi%20there”

bool authInitialEmpty: If this flag is set, the authentication client framework will send an empty Authorization header in each initial request. Default is no.

string authInitialAlgorithm: Specify the algorithm to use when empty Authorization header is to be sent for each initial request (see above)

TransportId transportId

Optionally bind this account to specific transport. This normally is not a good idea, as account should be able to send requests using any available transports according to the destination. But some application may want to have explicit control over the transport to use, so in that case it can set this field.

Default: -1 (PJSUA_INVALID_ID)

AccountCallConfig¶

struct AccountCallConfig : public pj::PersistentObject

Account’s call settings. This will be specified in AccountConfig.

Public Functions

inline AccountCallConfig(): Default constructor

virtual void readObject (const ContainerNode &node) PJSUA2_THROW(Error)

Read this object from a container node.

Parameters: node – Container to read values from.

virtual void writeObject (ContainerNode &node) const PJSUA2_THROW(Error)

Write this object to a container node.

Parameters: node – Container to write values to.

Public Members

pjsua_call_hold_type holdType

Specify how to offer call hold to remote peer. Please see the documentation on pjsua_call_hold_type for more info.

Default: PJSUA_CALL_HOLD_TYPE_DEFAULT

pjsua_100rel_use prackUse

Specify how support for reliable provisional response (100rel/ PRACK) should be used for all sessions in this account. See the documentation of pjsua_100rel_use enumeration for more info.

Default: PJSUA_100REL_NOT_USED

pjsua_sip_timer_use timerUse

Specify the usage of Session Timers for all sessions. See the pjsua_sip_timer_use for possible values.

Default: PJSUA_SIP_TIMER_OPTIONAL

unsigned timerMinSESec: Specify minimum Session Timer expiration period, in seconds. Must not be lower than 90. Default is 90.

unsigned timerSessExpiresSec: Specify Session Timer expiration period, in seconds. Must not be lower than timerMinSE. Default is 1800.

AccountPresConfig¶

struct AccountPresConfig : public pj::PersistentObject

Account presence config. This will be specified in AccountConfig.

Public Functions

virtual void readObject (const ContainerNode &node) PJSUA2_THROW(Error)

Read this object from a container node.

Parameters: node – Container to read values from.

virtual void writeObject (ContainerNode &node) const PJSUA2_THROW(Error)

Write this object to a container node.

Parameters: node – Container to write values to.

Public Members

SipHeaderVector headers: The optional custom SIP headers to be put in the presence subscription request.

bool publishEnabled

If this flag is set, the presence information of this account will be PUBLISH-ed to the server where the account belongs.

Default: PJ_FALSE

bool publishQueue

Specify whether the client publication session should queue the PUBLISH request should there be another PUBLISH transaction still pending. If this is set to false, the client will return error on the PUBLISH request if there is another PUBLISH transaction still in progress.

Default: PJSIP_PUBLISHC_QUEUE_REQUEST (TRUE)

unsigned publishShutdownWaitMsec

Maximum time to wait for unpublication transaction(s) to complete during shutdown process, before sending unregistration. The library tries to wait for the unpublication (un-PUBLISH) to complete before sending REGISTER request to unregister the account, during library shutdown process. If the value is set too short, it is possible that the unregistration is sent before unpublication completes, causing unpublication request to fail.

Value is in milliseconds.

Default: PJSUA_UNPUBLISH_MAX_WAIT_TIME_MSEC (2000)

string pidfTupleId: Optional PIDF tuple ID for outgoing PUBLISH and NOTIFY. If this value is not specified, a random string will be used.

AccountMwiConfig¶

struct AccountMwiConfig : public pj::PersistentObject

Account MWI (Message Waiting Indication) settings. This will be specified in AccountConfig.

Public Functions

virtual void readObject (const ContainerNode &node) PJSUA2_THROW(Error)

Read this object from a container node.

Parameters: node – Container to read values from.

virtual void writeObject (ContainerNode &node) const PJSUA2_THROW(Error)

Write this object to a container node.

Parameters: node – Container to write values to.

Public Members

bool enabled

Subscribe to message waiting indication events (RFC 3842).

See also UaConfig.mwiUnsolicitedEnabled setting.

Default: FALSE

unsigned expirationSec

Specify the default expiration time (in seconds) for Message Waiting Indication (RFC 3842) event subscription. This must not be zero.

Default: PJSIP_MWI_DEFAULT_EXPIRES (3600)

AccountNatConfig¶

struct AccountNatConfig : public pj::PersistentObject

Account’s NAT (Network Address Translation) settings. This will be specified in AccountConfig.

Public Functions

inline AccountNatConfig(): Default constructor

virtual void readObject (const ContainerNode &node) PJSUA2_THROW(Error)

Read this object from a container node.

Parameters: node – Container to read values from.

virtual void writeObject (ContainerNode &node) const PJSUA2_THROW(Error)

Write this object to a container node.

Parameters: node – Container to write values to.

Public Members

pjsua_stun_use sipStunUse

Control the use of STUN for the SIP signaling.

Default: PJSUA_STUN_USE_DEFAULT

pjsua_stun_use mediaStunUse

Control the use of STUN for the media transports.

Default: PJSUA_STUN_USE_DEFAULT

pjsua_nat64_opt nat64Opt

Specify NAT64 options.

Default: PJSUA_NAT64_DISABLED

bool iceEnabled

Enable ICE for the media transport.

Default: False

int iceMaxHostCands

Set the maximum number of ICE host candidates.

Default: -1 (maximum not set)

bool iceAggressiveNomination

Specify whether to use aggressive nomination.

Default: True

unsigned iceNominatedCheckDelayMsec

For controlling agent if it uses regular nomination, specify the delay to perform nominated check (connectivity check with USE-CANDIDATE attribute) after all components have a valid pair.

Default value is PJ_ICE_NOMINATED_CHECK_DELAY.

int iceWaitNominationTimeoutMsec

For a controlled agent, specify how long it wants to wait (in milliseconds) for the controlling agent to complete sending connectivity check with nominated flag set to true for all components after the controlled agent has found that all connectivity checks in its checklist have been completed and there is at least one successful (but not nominated) check for every component.

Default value for this option is ICE_CONTROLLED_AGENT_WAIT_NOMINATION_TIMEOUT. Specify -1 to disable this timer.

bool iceNoRtcp

Disable RTCP component.

Default: False

bool iceAlwaysUpdate

Always send re-INVITE/UPDATE after ICE negotiation regardless of whether the default ICE transport address is changed or not. When this is set to False, re-INVITE/UPDATE will be sent only when the default ICE transport address is changed.

Default: yes

bool turnEnabled: Enable TURN candidate in ICE.

string turnServer: Specify TURN domain name or host name, in in “DOMAIN:PORT” or “HOST:PORT” format.

pj_turn_tp_type turnConnType

Specify the connection type to be used to the TURN server. Valid values are PJ_TURN_TP_UDP or PJ_TURN_TP_TCP.

Default: PJ_TURN_TP_UDP

string turnUserName: Specify the username to authenticate with the TURN server.

int turnPasswordType: Specify the type of password. Currently this must be zero to indicate plain-text password will be used in the password.

string turnPassword: Specify the password to authenticate with the TURN server.

int contactRewriteUse

This option is used to update the transport address and the Contact header of REGISTER request. When this option is enabled, the library will keep track of the public IP address from the response of REGISTER request. Once it detects that the address has changed, it will unregister current Contact, update the Contact with transport address learned from Via header, and register a new Contact to the registrar. This will also update the public name of UDP transport if STUN is configured.

AccountMediaConfig¶

struct AccountMediaConfig : public pj::PersistentObject

Account media config (applicable for both audio and video). This will be specified in AccountConfig.

Public Functions

inline AccountMediaConfig(): Default constructor

virtual void readObject (const ContainerNode &node) PJSUA2_THROW(Error)

Read this object from a container node.

Parameters: node – Container to read values from.

virtual void writeObject (ContainerNode &node) const PJSUA2_THROW(Error)

Write this object to a container node.

Parameters: node – Container to write values to.

Public Members

TransportConfig transportConfig: Media transport (RTP) configuration.

bool lockCodecEnabled

If remote sends SDP answer containing more than one format or codec in the media line, send re-INVITE or UPDATE with just one codec to lock which codec to use.

Default: True (Yes).

bool streamKaEnabled

Specify whether stream keep-alive and NAT hole punching with non-codec-VAD mechanism (see PJMEDIA_STREAM_ENABLE_KA) is enabled for this account.

Default: False

pjmedia_srtp_use srtpUse

Specify whether secure media transport should be used for this account. Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and PJMEDIA_SRTP_MANDATORY.

Default: PJSUA_DEFAULT_USE_SRTP

int srtpSecureSignaling

Specify whether SRTP requires secure signaling to be used. This option is only used when use_srtp option above is non-zero.

Valid values are: 0: SRTP does not require secure signaling 1: SRTP requires secure transport such as TLS 2: SRTP requires secure end-to-end transport (SIPS)

Default: PJSUA_DEFAULT_SRTP_SECURE_SIGNALING

SrtpOpt srtpOpt: Specify SRTP settings, like cryptos and keying methods.

pjsua_ipv6_use ipv6Use: Specify whether IPv6 should be used on media. Default is not used.

bool rtcpMuxEnabled: Enable RTP and RTCP multiplexing.

RtcpFbConfig rtcpFbConfig: RTCP Feedback settings.

AccountVideoConfig¶

struct AccountVideoConfig : public pj::PersistentObject

Account video config. This will be specified in AccountConfig.

Public Functions

inline AccountVideoConfig(): Default constructor

virtual void readObject (const ContainerNode &node) PJSUA2_THROW(Error)

Read this object from a container node.

Parameters: node – Container to read values from.

virtual void writeObject (ContainerNode &node) const PJSUA2_THROW(Error)

Write this object to a container node.

Parameters: node – Container to write values to.

Public Members

bool autoShowIncoming

Specify whether incoming video should be shown to screen by default. This applies to incoming call (INVITE), incoming re-INVITE, and incoming UPDATE requests.

Regardless of this setting, application can detect incoming video by implementing on_call_media_state() callback and enumerating the media stream(s) with pjsua_call_get_info(). Once incoming video is recognised, application may retrieve the window associated with the incoming video and show or hide it with pjsua_vid_win_set_show().

Default: False

bool autoTransmitOutgoing

Specify whether outgoing video should be activated by default when making outgoing calls and/or when incoming video is detected. This applies to incoming and outgoing calls, incoming re-INVITE, and incoming UPDATE. If the setting is non-zero, outgoing video transmission will be started as soon as response to these requests is sent (or received).

Regardless of the value of this setting, application can start and stop outgoing video transmission with pjsua_call_set_vid_strm().

Default: False

unsigned windowFlags

Specify video window’s flags. The value is a bitmask combination of pjmedia_vid_dev_wnd_flag.

Default: 0

pjmedia_vid_dev_index defaultCaptureDevice

Specify the default capture device to be used by this account. If vidOutAutoTransmit is enabled, this device will be used for capturing video.

Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV

pjmedia_vid_dev_index defaultRenderDevice

Specify the default rendering device to be used by this account.

Default: PJMEDIA_VID_DEFAULT_RENDER_DEV

pjmedia_vid_stream_rc_method rateControlMethod

Rate control method.

Default: PJMEDIA_VID_STREAM_RC_SIMPLE_BLOCKING.

unsigned rateControlBandwidth

Upstream/outgoing bandwidth. If this is set to zero, the video stream will use codec maximum bitrate setting.

Default: 0 (follow codec maximum bitrate).

unsigned startKeyframeCount

The number of keyframe to be sent after the stream is created.

Default: PJMEDIA_VID_STREAM_START_KEYFRAME_CNT

unsigned startKeyframeInterval

The keyframe sending interval after the stream is created.

Default: PJMEDIA_VID_STREAM_START_KEYFRAME_INTERVAL_MSEC

Callback Parameters¶

struct OnIncomingCallParam

This structure contains parameters for onIncomingCall() account callback.

Public Members

int callId: The library call ID allocated for the new call.

SipRxData rdata: The incoming INVITE request.

struct OnRegStartedParam

This structure contains parameters for onRegStarted() account callback.

Public Members

bool renew: True for registration and False for unregistration.

struct OnRegStateParam

This structure contains parameters for onRegState() account callback.

Public Members

pj_status_t status: Registration operation status.

pjsip_status_code code: SIP status code received.

string reason: SIP reason phrase received.

SipRxData rdata: The incoming message.

unsigned expiration: Next expiration interval.

struct OnIncomingSubscribeParam

This structure contains parameters for onIncomingSubscribe() callback.

Public Members

void *srvPres: Server presence subscription instance. If application delays the acceptance of the request, it will need to specify this object when calling Account::presNotify().

string fromUri: Sender URI.

SipRxData rdata: The incoming message.

pjsip_status_code code: The status code to respond to the request. The default value is 200. Application may set this to other final status code to accept or reject the request.

string reason: The reason phrase to respond to the request.

SipTxOption txOption: Additional data to be sent with the response, if any.

struct OnInstantMessageParam

Parameters for onInstantMessage() account callback.

Public Members

string fromUri: Sender From URI.

string toUri: To URI of the request.

string contactUri: Contact URI of the sender.

string contentType: MIME type of the message body.

string msgBody: The message body.

SipRxData rdata: The whole message.

struct OnInstantMessageStatusParam

Parameters for onInstantMessageStatus() account callback.

Public Members

Token userData: Token or a user data that was associated with the pager transmission.

string toUri: Destination URI.

string msgBody: The message body.

pjsip_status_code code: The SIP status code of the transaction.

string reason: The reason phrase of the transaction.

SipRxData rdata: The incoming response that causes this callback to be called. If the transaction fails because of time out or transport error, the content will be empty.

struct OnTypingIndicationParam

Parameters for onTypingIndication() account callback.

Public Members

string fromUri: Sender/From URI.

string toUri: To URI.

string contactUri: The Contact URI.

bool isTyping: Boolean to indicate if sender is typing.

SipRxData rdata: The whole message buffer.

struct OnMwiInfoParam

Parameters for onMwiInfo() account callback.

Public Members

pjsip_evsub_state state: MWI subscription state.

SipRxData rdata: The whole message buffer.

struct PresNotifyParam

Parameters for presNotify() account method.

Public Members

void *srvPres: Server presence subscription instance.

pjsip_evsub_state state: Server presence subscription state to set.

string stateStr: Optionally specify the state string name, if state is not “active”, “pending”, or “terminated”.

string reason: If the new state is PJSIP_EVSUB_STATE_TERMINATED, optionally specify the termination reason.

bool withBody: If the new state is PJSIP_EVSUB_STATE_TERMINATED, this specifies whether the NOTIFY request should contain message body containing account’s presence information.

SipTxOption txOption: Optional list of headers to be sent with the NOTIFY request.

Other¶

class FindBuddyMatch

Wrapper class for Buddy matching algo.

Default algo is a simple substring lookup of search-token in the Buddy URIs, with case sensitive. Application can implement its own matching algo by overriding this class and specifying its instance in Account::findBuddy().

Public Functions

inline virtual bool match(const string &token, const Buddy &buddy): Default algo implementation.

inline virtual ~FindBuddyMatch(): Destructor.