8. Buddy (Presence)

Presence feature in PJSUA2 centers around Buddy class. This class represents a remote buddy (a person, or a SIP endpoint).

Subclassing the Buddy class

To use the Buddy class, normally application SHOULD create its own subclass, such as:

class MyBuddy : public Buddy
{
public:
    MyBuddy() {}
    ~MyBuddy() {}

    virtual void onBuddyState();
};

In its subclass, application can implement the buddy callback to get the notifications on buddy state change.

Subscribing to Buddy’s Presence Status

To subscribe to buddy’s presence status, you need to add a buddy object and subscribe to buddy’s presence status. The snippet below shows a sample code to achieve these:

BuddyConfig cfg;
cfg.uri = "sip:alice@example.com";
MyBuddy buddy;
try {
    buddy.create(*acc, cfg);
    buddy.subscribePresence(true);
} catch(Error& err) {
}

Then you can get the buddy’s presence state change inside the onBuddyState() callback:

void MyBuddy::onBuddyState()
{
    BuddyInfo bi = getInfo();
    cout << "Buddy " << bi.uri << " is " << bi.presStatus.statusText << endl;
}

For more information, please see Buddy class reference documentation.

Responding to Presence Subscription Request

By default, incoming presence subscription to an account will be accepted automatically. You will probably want to change this behavior, for example only to automatically accept subscription if it comes from one of the buddy in the buddy list, and for anything else prompt the user if he/she wants to accept the request.

This can be done by overriding the onIncomingSubscribe() method of the Account class. Please see the documentation of this method for more info.

Changing Account’s Presence Status

To change account’s presence status, you can use the function Account.setOnlineStatus() to set basic account’s presence status (i.e. available or not available) and optionally, some extended information (e.g. busy, away, on the phone, etc), such as:

try {
    PresenceStatus ps;
    ps.status = PJSUA_BUDDY_STATUS_ONLINE;
    // Optional, set the activity and some note
    ps.activity = PJRPID_ACTIVITY_BUSY;
    ps.note = "On the phone";
    acc->setOnlineStatus(ps);
} catch(Error& err) {
}

When the presence status is changed, the account will publish the new status to all of its presence subscriber, either with PUBLISH request or NOTIFY request, or both, depending on account configuration.

Instant Messaging(IM)

You can send IM using Buddy.sendInstantMessage(). The transmission status of outgoing instant messages is reported in Account.onInstantMessageStatus() callback method of Account class.

In addition to sending instant messages, you can also send typing indication to remote buddy using Buddy.sendTypingIndication().

Incoming IM and typing indication received not within the scope of a call will be reported in the callback functions Account.onInstantMessage() and Account.onTypingIndication().

Alternatively, you can send IM and typing indication within a call by using Call.sendInstantMessage() and Call.sendTypingIndication(). For more information, please see Call documentation.

Class Reference

Buddy

class Buddy

Buddy.

This is a lite wrapper class for PJSUA-LIB buddy, i.e: this class only maintains one data member, PJSUA-LIB buddy ID, and the methods are simply proxies for PJSUA-LIB buddy operations.

Application can use create() to register a buddy to PJSUA-LIB, and the destructor of the original instance (i.e: the instance that calls create()) will unregister and delete the buddy from PJSUA-LIB. Application must delete all Buddy instances belong to an account before shutting down the account (via Account::shutdown()).

The library will not keep a list of Buddy instances, so any Buddy (or descendant) instances instantiated by application must be maintained and destroyed by the application itself. Any PJSUA2 APIs that return Buddy instance(s) such as Account::enumBuddies2() or Account::findBuddy2() will just return generated copy. All Buddy methods should work normally on this generated copy instance.

Public Functions

Buddy()

Constructor.

virtual ~Buddy()

Destructor.

Note that if the Buddy original instance (i.e: the instance that calls Buddy::create()) is destroyed, it will also delete the corresponding buddy in the PJSUA-LIB. While the destructor of a generated copy (i.e: Buddy instance returned by PJSUA2 APIs such as Account::enumBuddies2() or Account::findBuddy2()) will do nothing.

void create(Account &acc, const BuddyConfig &cfg)

Create buddy and register the buddy to PJSUA-LIB.

Note that application should maintain the Buddy original instance, i.e: the instance that calls this create() method as it is only the original instance destructor that will delete the underlying Buddy in PJSUA-LIB.

Parameters

• acc: The account for this buddy.

• cfg: The buddy config.

bool isValid() const

Check if this buddy is valid.

Return

True if it is.

BuddyInfo getInfo() const

Get detailed buddy info.

Return

Buddy info.

void subscribePresence(bool subscribe)

Enable/disable buddy’s presence monitoring.

Once buddy’s presence is subscribed, application will be informed about buddy’s presence status changed via onBuddyState() callback.

Parameters

• subscribe: Specify true to activate presence subscription.

void updatePresence(void)

Update the presence information for the buddy.

Although the library periodically refreshes the presence subscription for all buddies, some application may want to refresh the buddy’s presence subscription immediately, and in this case it can use this function to accomplish this.

Note that the buddy’s presence subscription will only be initiated if presence monitoring is enabled for the buddy. See subscribePresence() for more info. Also if presence subscription for the buddy is already active, this function will not do anything.

Once the presence subscription is activated successfully for the buddy, application will be notified about the buddy’s presence status in the onBuddyState() callback.

void sendInstantMessage(const SendInstantMessageParam &prm)

Send instant messaging outside dialog, using this buddy’s specified account for route set and authentication.

Parameters

• prm: Sending instant message parameter.

void sendTypingIndication(const SendTypingIndicationParam &prm)

Send typing indication outside dialog.

Parameters

• prm: Sending instant message parameter.

virtual void onBuddyState()

Notify application when the buddy state has changed.

Application may then query the buddy info to get the details.

virtual void onBuddyEvSubState(OnBuddyEvSubStateParam &prm)

Notify application when the state of client subscription session associated with a buddy has changed.

Application may use this callback to retrieve more detailed information about the state changed event.

Parameters

• prm: Callback parameter.

Status

struct PresenceStatus

This describes presence status.

Info

struct BuddyInfo

This structure describes buddy info, which can be retrieved by via Buddy::getInfo().

Config

struct BuddyConfig : public pj::PersistentObject

This structure describes buddy configuration when adding a buddy to the buddy list with Buddy::create().