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) PJSUA2_THROW(Error)

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.

Returns: True if it is.

BuddyInfo getInfo () const PJSUA2_THROW(Error)

Get detailed buddy info.

Returns: Buddy info.

void subscribePresence (bool subscribe) PJSUA2_THROW(Error)

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) PJSUA2_THROW(Error)

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) PJSUA2_THROW(Error)

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) PJSUA2_THROW(Error)

Send typing indication outside dialog.

Parameters: prm – Sending instant message parameter.

inline virtual void onBuddyState(): Notify application when the buddy state has changed. Application may then query the buddy info to get the details.

inline 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.

Public Functions

PresenceStatus(): Constructor.

Public Members

pjsua_buddy_status status: Buddy’s online status.

string statusText: Text to describe buddy’s online status.

pjrpid_activity activity: Activity type.

string note: Optional text describing the person/element.

string rpidId: Optional RPID ID string.

Info¶

struct BuddyInfo

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

Public Functions

inline BuddyInfo(): Default constructor

void fromPj(const pjsua_buddy_info &pbi): Import from pjsip structure

Public Members

string uri: The full URI of the buddy, as specified in the configuration.

string contact: Buddy’s Contact, only available when presence subscription has been established to the buddy.

bool presMonitorEnabled: Flag to indicate that we should monitor the presence information for this buddy (normally yes, unless explicitly disabled).

pjsip_evsub_state subState: If presMonitorEnabled is true, this specifies the last state of the presence subscription. If presence subscription session is currently active, the value will be PJSIP_EVSUB_STATE_ACTIVE. If presence subscription request has been rejected, the value will be PJSIP_EVSUB_STATE_TERMINATED, and the termination reason will be specified in subTermReason.

string subStateName: String representation of subscription state.

pjsip_status_code subTermCode: Specifies the last presence subscription termination code. This would return the last status of the SUBSCRIBE request. If the subscription is terminated with NOTIFY by the server, this value will be set to 200, and subscription termination reason will be given in the subTermReason field.

string subTermReason: Specifies the last presence subscription termination reason. If presence subscription is currently active, the value will be empty.

PresenceStatus presStatus: Presence status.

Config¶

struct BuddyConfig : public pj::PersistentObject

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

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 uri: Buddy URL or name address.

bool subscribe: Specify whether presence subscription should start immediately.