PJSUA-API Buddy, Presence, and Instant Messaging
[PJSUA API - High Level Softphone API for C/C++ and Python]

---

Detailed Description

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

Data Structures
struct	pjsua_buddy_config
struct	pjsua_buddy_info
Defines
#define	PJSUA_MAX_BUDDIES   256
#define	PJSUA_PRES_TIMER   300
Enumerations
enum	pjsua_buddy_status { PJSUA_BUDDY_STATUS_UNKNOWN, PJSUA_BUDDY_STATUS_ONLINE, PJSUA_BUDDY_STATUS_OFFLINE }
Functions
void	pjsua_buddy_config_default (pjsua_buddy_config *cfg)
unsigned	pjsua_get_buddy_count (void)
pj_bool_t	pjsua_buddy_is_valid (pjsua_buddy_id buddy_id)
pj_status_t	pjsua_enum_buddies (pjsua_buddy_id ids[], unsigned *count)
pjsua_buddy_id	pjsua_buddy_find (const pj_str_t *uri)
pj_status_t	pjsua_buddy_get_info (pjsua_buddy_id buddy_id, pjsua_buddy_info *info)
pj_status_t	pjsua_buddy_set_user_data (pjsua_buddy_id buddy_id, void *user_data)
void *	pjsua_buddy_get_user_data (pjsua_buddy_id buddy_id)
pj_status_t	pjsua_buddy_add (const pjsua_buddy_config *buddy_cfg, pjsua_buddy_id *p_buddy_id)
pj_status_t	pjsua_buddy_del (pjsua_buddy_id buddy_id)
pj_status_t	pjsua_buddy_subscribe_pres (pjsua_buddy_id buddy_id, pj_bool_t subscribe)
pj_status_t	pjsua_buddy_update_pres (pjsua_buddy_id buddy_id)
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)
void	pjsua_pres_dump (pj_bool_t verbose)
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)
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)
Variables
const pjsip_method	pjsip_message_method

---

Define Documentation

#define PJSUA_MAX_BUDDIES   256

Max buddies in buddy list.

#define PJSUA_PRES_TIMER   300

This specifies how long the library should retry resending SUBSCRIBE if the previous SUBSCRIBE failed.

Default: 300 seconds

---

Enumeration Type Documentation

enum pjsua_buddy_status

This enumeration describes basic buddy's online status.

Enumerator:

PJSUA_BUDDY_STATUS_UNKNOWN	Online status is unknown (possibly because no presence subscription has been established).
PJSUA_BUDDY_STATUS_ONLINE	Buddy is known to be online.
PJSUA_BUDDY_STATUS_OFFLINE	Buddy is offline.

---

Function Documentation

void pjsua_buddy_config_default

(

pjsua_buddy_config *

cfg

)

Set default values to the buddy config.

Python:

    buddy_cfg = py_pjsua.buddy_config_default()

unsigned pjsua_get_buddy_count

(

void

)

Get total number of buddies.

Returns:

Number of buddies.

Python:

    buddy_count = py_pjsua.get_buddy_count()

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.

Python:

    is_valid = py_pjsua.buddy_is_valid(buddy_id)

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.

Python:

The Python function takes no argument and returns list of buddy IDs:

    [buddy_ids] = py_pjsua.enum_buddies()

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.

Python:

    buddy_info = py_pjsua.buddy_get_info(buddy_id)

The function returns None if buddy_id is not valid.

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.

Python:

The function returns (status, buddy_id) tuple:

    status, buddy_id = py_pjsua.buddy_add(buddy_cfg)

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.

Python:

    status = py_pjsua.buddy_del(buddy_id)

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.

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.

Python:

    status = py_pjsua.buddy_subscribe_pres(buddy_id, subscribe)

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

Python:

    py_pjsua.pres_dump()

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.
	msg_data	Optional list of headers etc to be included in outgoing request. The body descriptor in the msg_data is ignored.
	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.

Python:

    status = py_pjsua.im_send(acc_id, to, mime_type, content, msg_data, user_data)

Arguments mime_type and msg_data may be set to None if not required.

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.

Python:

    status = py_pjsua.im_typing(acc_id, to, is_typing, msg_data)

Argument msg_data may be set to None if not requried.

---

Variable Documentation

const pjsip_method pjsip_message_method

The MESSAGE method (defined in pjsua_im.c)