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)

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)

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.

Return

True if it is.

void setDefault()

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.

Return

True if this is the default account.

int getId() const

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

Return

Integer greater than or equal to zero.

AccountInfo getInfo() const

Get account info.

Return

Account info.

void setRegistration(bool renew)

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)

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)

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)

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

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

Enumerate all buddies of the account.

Return

The buddy list.

BuddyVector2 enumBuddies2() const

Enumerate all buddies of the account.

Return

The buddy list.

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

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.

Return

The pointer to buddy.

Parameters
  • uri: The buddy URI.

  • buddy_match: The buddy match algo.

Buddy findBuddy2(string uri) const

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

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

Return

The pointer to buddy.

Parameters
  • uri: The buddy URI.

virtual void onIncomingCall(OnIncomingCallParam &prm)

Notify application on incoming call.

Parameters
  • prm: Callback parameter.

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.

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.

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.

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.

virtual void onInstantMessageStatus(OnInstantMessageStatusParam &prm)

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

Parameters
  • prm: Callback parameter.

virtual void onTypingIndication(OnTypingIndicationParam &prm)

Notify application about typing indication.

Parameters
  • prm: Callback parameter.

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.

Return

The Account instance or NULL if not found.

Parameters
  • acc_id: The account ID to lookup

AccountInfo

struct AccountInfo

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

Public Functions

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)

Read this object from a container node.

Parameters
  • node: Container to read values from.

virtual void writeObject(ContainerNode &node) const

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)

Read this object from a container node.

Parameters
  • node: Container to read values from.

virtual void writeObject(ContainerNode &node) const

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)

Read this object from a container node.

Parameters
  • node: Container to read values from.

virtual void writeObject(ContainerNode &node) const

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)

See

Account::setTransport()

AccountCallConfig

struct AccountCallConfig : public pj::PersistentObject

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

Public Functions

AccountCallConfig()

Default constructor

virtual void readObject(const ContainerNode &node)

Read this object from a container node.

Parameters
  • node: Container to read values from.

virtual void writeObject(ContainerNode &node) const

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)

Read this object from a container node.

Parameters
  • node: Container to read values from.

virtual void writeObject(ContainerNode &node) const

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)

Read this object from a container node.

Parameters
  • node: Container to read values from.

virtual void writeObject(ContainerNode &node) const

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

AccountNatConfig()

Default constructor

virtual void readObject(const ContainerNode &node)

Read this object from a container node.

Parameters
  • node: Container to read values from.

virtual void writeObject(ContainerNode &node) const

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.

See also contactRewriteMethod field.

Default: TRUE

int contactRewriteMethod

Specify how Contact update will be done with the registration, if contactRewriteEnabled is enabled. The value is bitmask combination of pjsua_contact_rewrite_method. See also pjsua_contact_rewrite_method.

Value PJSUA_CONTACT_REWRITE_UNREGISTER(1) is the legacy behavior.

Default value: PJSUA_CONTACT_REWRITE_METHOD (PJSUA_CONTACT_REWRITE_NO_UNREG | PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE)

int contactUseSrcPort

Specify if source TCP port should be used as the initial Contact address if TCP/TLS transport is used. Note that this feature will be automatically turned off when nameserver is configured because it may yield different destination address due to DNS SRV resolution. Also some platforms are unable to report the local address of the TCP socket when it is still connecting. In these cases, this feature will also be turned off.

Default: 1 (yes).

int viaRewriteUse

This option is used to overwrite the “sent-by” field of the Via header for outgoing messages with the same interface address as the one in the REGISTER request, as long as the request uses the same transport instance as the previous REGISTER request.

Default: TRUE

int sdpNatRewriteUse

This option controls whether the IP address in SDP should be replaced with the IP address found in Via header of the REGISTER response, ONLY when STUN and ICE are not used. If the value is FALSE (the original behavior), then the local IP address will be used. If TRUE, and when STUN and ICE are disabled, then the IP address found in registration response will be used.

Default: PJ_FALSE (no)

int sipOutboundUse

Control the use of SIP outbound feature. SIP outbound is described in RFC 5626 to enable proxies or registrar to send inbound requests back to UA using the same connection initiated by the UA for its registration. This feature is highly useful in NAT-ed deployemtns, hence it is enabled by default.

Note: currently SIP outbound can only be used with TCP and TLS transports. If UDP is used for the registration, the SIP outbound feature will be silently ignored for the account.

Default: TRUE

string sipOutboundInstanceId

Specify SIP outbound (RFC 5626) instance ID to be used by this account. If empty, an instance ID will be generated based on the hostname of this agent. If application specifies this parameter, the value will look like “<urn:uuid:00000000-0000-1000-8000-AABBCCDDEEFF>” without the double-quotes.

Default: empty

string sipOutboundRegId

Specify SIP outbound (RFC 5626) registration ID. The default value is empty, which would cause the library to automatically generate a suitable value.

Default: empty

unsigned udpKaIntervalSec

Set the interval for periodic keep-alive transmission for this account. If this value is zero, keep-alive will be disabled for this account. The keep-alive transmission will be sent to the registrar’s address, after successful registration.

Default: 15 (seconds)

string udpKaData

Specify the data to be transmitted as keep-alive packets.

Default: CR-LF

AccountMediaConfig

struct AccountMediaConfig : public pj::PersistentObject

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

Public Functions

AccountMediaConfig()

Default constructor

virtual void readObject(const ContainerNode &node)

Read this object from a container node.

Parameters
  • node: Container to read values from.

virtual void writeObject(ContainerNode &node) const

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

AccountVideoConfig()

Default constructor

virtual void readObject(const ContainerNode &node)

Read this object from a container node.

Parameters
  • node: Container to read values from.

virtual void writeObject(ContainerNode &node) const

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

virtual bool match(const string &token, const Buddy &buddy)

Default algo implementation.

virtual ~FindBuddyMatch()

Destructor.