Presence

group PJSUA2_PRES

Typedefs

typedef std::vector<Buddy*> BuddyVector

Warning: deprecated, use BuddyVector2 instead.

Array of buddies.

typedef std::vector<Buddy> BuddyVector2

Array of buddies

struct PresenceStatus

#include <presence.hpp>

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.

struct BuddyConfig : public pj::PersistentObject

#include <presence.hpp>

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

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 uri

Buddy URL or name address.

bool subscribe

Specify whether presence subscription should start immediately.

bool subscribe_dlg_event

Specify whether we should immediately subscribe to the buddy’s dialog event, such as for Busy Lamp Field (BLF) feature. Note that only one subscription (presence or dialog event) can be active at any time.

struct BuddyInfo

#include <presence.hpp>

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.

pjsua_acc_id accId

The account ID associated with this buddy. If not associated with any account, the value will be PJSUA_INVALID_ID.

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.

struct OnBuddyEvSubStateParam

#include <presence.hpp>

This structure contains parameters for Buddy::onBuddyEvSubState() callback.

Public Members

SipEvent e

• The event which triggers state change event.

class Buddy

#include <presence.hpp>

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.

IMPORTANT: Application must make sure that the Account instance remains valid for the entire lifetime of the Buddy object.

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.

int getId() const

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

Returns:

Integer greater than or equal to zero.

BuddyInfo getInfo() const

Get detailed buddy info.

Returns:

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 subscribeDlgEvent(bool subscribe)

Enable/disable buddy’s dialog event monitoring. Once buddy’s dialog event is subscribed, application will be informed about buddy’s dialog info status change via onBuddyDlgEventState() callback.

Note that only one subscription (presence or dialog event) can be active at any time.

Parameters:

subscribe – Specify non-zero to activate dialog event subscription to the specified buddy.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

void updateDlgEvent(void)

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

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

Once the dialog event subscription is activated successfully for the buddy, application will be notified about the buddy’s dialog info status in the onBuddyDlgEventState() 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.

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

Notify application when the buddy dialog state has changed. Application may then query the buddy into 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.

inline virtual void onBuddyEvSubDlgEventState(OnBuddyEvSubStateParam &prm)

Notify application when the state of client subscription session associated with a buddy dialog state has changed. Application may use this callback to retrieve more detailed information about the state changed event.