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 pj::Buddy

Buddy.

Public Functions
Buddy()

Constructor.

virtual ~Buddy()

Destructor.

Note that if the Buddy instance is deleted, it will also delete the corresponding buddy in the PJSUA-LIB.

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

Create buddy and register the buddy to 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.

Status

struct pj::PresenceStatus

This describes presence status.

Info

struct pj::BuddyInfo

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

Config

struct pj::BuddyConfig

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