5. 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()
    {
        // Invoke shutdown() first..
        shutdown();
        // ..before deleting any member objects.
    }

    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. Please also note that 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.

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().

Account Settings¶

AccountConfig¶

struct AccountConfig : public pj::PersistentObject ¶: Account configuration.

AccoutRegConfig¶

struct AccountRegConfig : public pj::PersistentObject ¶

Account registration config.

This will be specified in AccountConfig.

AccountSipConfig¶

struct AccountSipConfig : public pj::PersistentObject ¶

Various SIP settings for the account.

This will be specified in AccountConfig.

AccountCallConfig¶

struct AccountCallConfig : public pj::PersistentObject ¶

Account’s call settings.

This will be specified in AccountConfig.

AccountPresConfig¶

struct AccountPresConfig : public pj::PersistentObject ¶

Account presence config.

This will be specified in AccountConfig.

AccountMwiConfig¶

struct AccountMwiConfig : public pj::PersistentObject ¶

Account MWI (Message Waiting Indication) settings.

This will be specified in AccountConfig.

AccountNatConfig¶

struct AccountNatConfig : public pj::PersistentObject ¶

Account’s NAT (Network Address Translation) settings.

This will be specified in AccountConfig.

AccountMediaConfig¶

struct AccountMediaConfig : public pj::PersistentObject ¶

Account media config (applicable for both audio and video).

This will be specified in AccountConfig.

AccountVideoConfig¶

struct AccountVideoConfig : public pj::PersistentObject ¶

Account video config.

This will be specified in AccountConfig.

Callback Parameters¶

struct OnIncomingCallParam¶: This structure contains parameters for onIncomingCall() account callback.

struct OnRegStartedParam¶: This structure contains parameters for onRegStarted() account callback.

struct OnRegStateParam¶: This structure contains parameters for onRegState() account callback.

struct OnIncomingSubscribeParam¶: This structure contains parameters for onIncomingSubscribe() callback.

struct OnInstantMessageParam¶: Parameters for onInstantMessage() account callback.

struct OnInstantMessageStatusParam¶: Parameters for onInstantMessageStatus() account callback.

struct OnTypingIndicationParam¶: Parameters for onTypingIndication() account callback.

struct OnMwiInfoParam¶: Parameters for onMwiInfo() account callback.

struct PresNotifyParam¶: Parameters for presNotify() account method.

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.

5. Accounts¶

Subclassing the Account class¶

Creating Userless Accounts¶

Creating Account¶

Account Configurations¶

Account Operations¶

Class Reference¶

Account¶

AccountInfo¶

Account Settings¶

AccountConfig¶

AccoutRegConfig¶

AccountSipConfig¶

AccountCallConfig¶

AccountPresConfig¶

AccountMwiConfig¶

AccountNatConfig¶

AccountMediaConfig¶

AccountVideoConfig¶

Callback Parameters¶

Other¶

Table of Contents

Previous topic

Next topic

This Page