Group PJSUA_LIB_BUDDY

group PJSUA_LIB_BUDDY

Buddy management, buddy’s presence, and instant messaging.

This section describes PJSUA-APIs related to buddies management, presence management, and instant messaging.

Defines

PJSUA_MAX_BUDDIES

Max buddies in buddy list.

PJSUA_PRES_TIMER

This specifies how long the library should wait before retrying failed SUBSCRIBE request, and there is no rule to automatically resubscribe (for example, no “retry-after” parameter in Subscription-State header).

This also controls the duration before failed PUBLISH request will be retried.

Default: 300 seconds

PJSUA_BUDDY_DLG_EVENT_INFO_BUF_SIZE

This specifies the buffer size of pjsua_buddy_dlg_event_info.

Default: 1024 bytes

Enums

enum pjsua_buddy_status

This enumeration describes basic buddy’s online status.

Values:

enumerator PJSUA_BUDDY_STATUS_UNKNOWN

Online status is unknown (possibly because no presence subscription has been established).

enumerator PJSUA_BUDDY_STATUS_ONLINE

Buddy is known to be online.

enumerator PJSUA_BUDDY_STATUS_OFFLINE

Buddy is offline.

Functions

void pjsua_buddy_config_default(pjsua_buddy_config *cfg)

Set default values to the buddy config.

unsigned pjsua_get_buddy_count(void)

Get total number of buddies.

Returns:

Number of buddies.

pj_bool_t pjsua_buddy_is_valid(pjsua_buddy_id buddy_id)

Check if buddy ID is valid.

Parameters:

buddy_id – Buddy ID to check.

Returns:

Non-zero if buddy ID is valid.

pj_status_t pjsua_enum_buddies(pjsua_buddy_id ids[], unsigned *count)

Enumerate all buddy IDs in the buddy list. Application then can use pjsua_buddy_get_info() to get the detail information for each buddy id.

Parameters:
  • ids – Array of ids to be initialized.

  • count – On input, specifies max elements in the array. On return, it contains actual number of elements that have been initialized.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pjsua_buddy_id pjsua_buddy_find(const pj_str_t *uri)

Find the buddy ID with the specified URI.

Parameters:

uri – The buddy URI.

Returns:

The buddy ID, or PJSUA_INVALID_ID if not found.

pj_status_t pjsua_buddy_get_info(pjsua_buddy_id buddy_id, pjsua_buddy_info *info)

Get detailed buddy info.

Parameters:
  • buddy_id – The buddy identification.

  • info – Pointer to receive information about buddy.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_buddy_get_dlg_event_info(pjsua_buddy_id buddy_id, pjsua_buddy_dlg_event_info *info)

Get detailed buddy dialog event info.

Parameters:
  • buddy_id – The buddy identification.

  • info – Pointer to receive information about buddy.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_buddy_set_user_data(pjsua_buddy_id buddy_id, void *user_data)

Set the user data associated with the buddy object.

Parameters:
  • buddy_id – The buddy identification.

  • user_data – Arbitrary application data to be associated with the buddy object.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

void *pjsua_buddy_get_user_data(pjsua_buddy_id buddy_id)

Get the user data associated with the budy object.

Parameters:

buddy_id – The buddy identification.

Returns:

The application data.

pj_status_t pjsua_buddy_add(const pjsua_buddy_config *buddy_cfg, pjsua_buddy_id *p_buddy_id)

Add new buddy to the buddy list. If presence subscription is enabled for this buddy, this function will also start the presence subscription session immediately.

Parameters:
  • buddy_cfg – Buddy configuration.

  • p_buddy_id – Pointer to receive buddy ID.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_buddy_del(pjsua_buddy_id buddy_id)

Delete the specified buddy from the buddy list. Any presence subscription to this buddy will be terminated.

Parameters:

buddy_id – Buddy identification.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_buddy_subscribe_pres(pjsua_buddy_id buddy_id, pj_bool_t subscribe)

Enable/disable buddy’s presence monitoring. Once buddy’s presence is subscribed, application will be informed about buddy’s presence status changed via on_buddy_state() callback.

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

Parameters:
  • buddy_id – Buddy identification.

  • subscribe – Specify non-zero to activate presence subscription to the specified buddy.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_buddy_subscribe_dlg_event(pjsua_buddy_id buddy_id, pj_bool_t 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 on_buddy_dlg_event_state() callback.

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

Parameters:
  • buddy_id – Buddy identification.

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

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_buddy_update_pres(pjsua_buddy_id buddy_id)

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 pjsua_buddy_subscribe_pres() 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 on_buddy_state() callback.

Parameters:

buddy_id – Buddy identification.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_buddy_update_dlg_event(pjsua_buddy_id buddy_id)

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 pjsua_buddy_subscribe_dlg_event() 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 on_buddy_dlg_event_state() callback.

Parameters:

buddy_id – Buddy identification.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_pres_notify(pjsua_acc_id acc_id, pjsua_srv_pres *srv_pres, pjsip_evsub_state state, const pj_str_t *state_str, const pj_str_t *reason, pj_bool_t with_body, const pjsua_msg_data *msg_data)

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 state to PJSIP_EVSUB_STATE_TERMINATED.

Parameters:
  • acc_id – Account ID.

  • srv_pres – Server presence subscription instance.

  • state – New state to set.

  • state_str – Optionally specify the state string name, if state is not “active”, “pending”, or “terminated”.

  • reason – If the new state is PJSIP_EVSUB_STATE_TERMINATED, optionally specify the termination reason.

  • with_body – If the new state is PJSIP_EVSUB_STATE_TERMINATED, this specifies whether the NOTIFY request should contain message body containing account’s presence information.

  • msg_data – Optional list of headers to be sent with the NOTIFY request.

Returns:

PJ_SUCCESS on success.

void pjsua_pres_dump(pj_bool_t verbose)

Dump presence subscriptions to log.

Parameters:

verbose – Yes or no.

pj_status_t pjsua_im_send(pjsua_acc_id acc_id, const pj_str_t *to, const pj_str_t *mime_type, const pj_str_t *content, const pjsua_msg_data *msg_data, void *user_data)

Send instant messaging outside dialog, using the specified account for route set and authentication.

Parameters:
  • acc_id – Account ID to be used to send the request.

  • to – Remote URI.

  • mime_type – Optional MIME type. If NULL, then “text/plain” is assumed.

  • content – The message content. Can be NULL if msg_data specifies body and/or multipart.

  • msg_data – Optional list of headers etc to be included in outgoing request. The body descriptor in the msg_data is ignored if parameter ‘content’ is set.

  • user_data – Optional user data, which will be given back when the IM callback is called.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_im_typing(pjsua_acc_id acc_id, const pj_str_t *to, pj_bool_t is_typing, const pjsua_msg_data *msg_data)

Send typing indication outside dialog.

Parameters:
  • acc_id – Account ID to be used to send the request.

  • to – Remote URI.

  • is_typing – If non-zero, it tells remote person that local person is currently composing an IM.

  • msg_data – Optional list of headers etc to be added to outgoing request.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

Variables

const pjsip_method pjsip_message_method

The MESSAGE method (defined in pjsua_im.c)

const pjsip_method pjsip_info_method

The INFO method (defined in pjsua_call.c)

struct pjsua_buddy_config
#include <pjsua.h>

This structure describes buddy configuration when adding a buddy to the buddy list with pjsua_buddy_add(). Application MUST initialize the structure with pjsua_buddy_config_default() to initialize this structure with default configuration.

Public Members

pj_str_t uri

Buddy URL or name address.

pj_bool_t subscribe

Specify whether presence subscription should start immediately. Note that only one subscription (presence or dialog event) can be active at any time.

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

void *user_data

Specify arbitrary application data to be associated with with the buddy object.

struct pjsua_buddy_info
#include <pjsua.h>

This structure describes buddy info, which can be retrieved by calling pjsua_buddy_get_info().

Public Members

pjsua_buddy_id id

The buddy ID.

pj_str_t uri

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

pj_str_t contact

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

pjsua_buddy_status status

Buddy’s online status.

pj_str_t status_text

Text to describe buddy’s online status.

pj_bool_t monitor_pres

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

pjsip_evsub_state sub_state

If monitor_pres is enabled, 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 sub_term_reason.

const char *sub_state_name

String representation of subscription state.

unsigned sub_term_code

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 sub_term_reason field.

pj_str_t sub_term_reason

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

pjrpid_element rpid

Extended RPID information about the person.

pjsip_pres_status pres_status

Extended presence info.

char buf_[512]

Internal buffer.

struct pjsua_buddy_dlg_event_info

Public Members

pjsua_buddy_id id

The buddy ID.

pj_str_t uri

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

pjsip_evsub_state sub_state

This specifies the last state of the dialog event subscription.

const char *sub_state_name

String representation of subscription state.

unsigned sub_term_code

Specifies the last dialog event subscription termination code.

pj_str_t sub_term_reason

Specifies the last dialog event subscription termination reason. If presence subscription is currently active, the value will be empty.

char buf_[1024]

Internal buffer.