liblinphone  3.6.1
Typedefs | Enumerations | Functions
Managing Buddies and buddy list and presence

Typedefs

typedef enum _LinphoneOnlineStatus LinphoneOnlineStatus
 
typedef struct _LinphoneFriend LinphoneFriend
 

Enumerations

Functions

LinphoneFriendlinphone_friend_new ()
 
LinphoneFriendlinphone_friend_new_with_addr (const char *addr)
 
void linphone_friend_destroy (LinphoneFriend *lf)
 
int linphone_friend_set_addr (LinphoneFriend *fr, const LinphoneAddress *address)
 
int linphone_friend_set_name (LinphoneFriend *lf, const char *name)
 
const LinphoneAddresslinphone_friend_get_address (const LinphoneFriend *lf)
 
bool_t linphone_friend_subscribes_enabled (const LinphoneFriend *lf)
 
int linphone_friend_enable_subscribes (LinphoneFriend *fr, bool_t val)
 
int linphone_friend_set_inc_subscribe_policy (LinphoneFriend *fr, LinphoneSubscribePolicy pol)
 
LinphoneSubscribePolicy linphone_friend_get_inc_subscribe_policy (const LinphoneFriend *lf)
 
void linphone_friend_edit (LinphoneFriend *fr)
 
void linphone_friend_done (LinphoneFriend *fr)
 
LinphoneOnlineStatus linphone_friend_get_status (const LinphoneFriend *lf)
 
const char * linphone_online_status_to_string (LinphoneOnlineStatus ss)
 
void linphone_core_set_presence_info (LinphoneCore *lc, int minutes_away, const char *alternative_contact, LinphoneOnlineStatus os)
 
LinphoneOnlineStatus linphone_core_get_presence_info (const LinphoneCore *lc)
 
void linphone_core_add_friend (LinphoneCore *lc, LinphoneFriend *fr)
 
void linphone_core_remove_friend (LinphoneCore *lc, LinphoneFriend *fr)
 
void linphone_core_reject_subscriber (LinphoneCore *lc, LinphoneFriend *lf)
 
const MSList * linphone_core_get_friend_list (const LinphoneCore *lc)
 
void linphone_core_notify_all_friends (LinphoneCore *lc, LinphoneOnlineStatus os)
 

Detailed Description

Buddies and buddy list
Each buddy is represented by a LinphoneFriend object created by function linphone_friend_new(). Buddy configuration parameters like sip uri or status publication policy for this friend are configurable for each buddy.
Here under a typical buddy creation:

LinphoneFriend* my_friend=linphone_friend_new_with_addr("sip:joe@sip.linphone.org"); /*creates friend object for buddy joe*/
linphone_friend_enable_subscribes(my_friend,TRUE); /*configure this friend to emit SUBSCRIBE message after being added to LinphoneCore*/
linphone_friend_set_inc_subscribe_policy(my_friend,LinphoneSPAccept); /* accept Incoming subscription request for this friend*/

friends status changes are reported by callback LinphoneCoreVTable.notify_presence_recv

static void notify_presence_recv_updated (struct _LinphoneCore *lc, LinphoneFriend *friend) {
const LinphoneAddress* friend_address = linphone_friend_get_address(friend);
printf("New state state [%s] for user id [%s] \n"
,linphone_address_as_string (friend_address));
}


Once created a buddy can be added to the buddy list using function linphone_core_add_friend() . Added friends will be notified about local status changes
Any subsequente modifications to LinphoneFriend must be first started by a call to function linphone_friend_edit() and validated by function linphone_friend_done()

linphone_friend_edit(my_friend); /* start editing friend */
linphone_friend_enable_subscribes(my_friend,FALSE); /*disable subscription for this friend*/
linphone_friend_done(my_friend); /*commit changes triggering an UNSUBSCRIBE message*/

Publishing presence status
Local presence status can be changed using function linphone_core_set_presence_info() .New status is propagated to all friends previously added to LinphoneCore.

Handling incoming subscription request
New incoming subscription requests are process according to the incoming subscription policy state for subscription initiated by members of the buddy list.
For incoming request comming from an unknown buddy, the call back LinphoneCoreVTable.new_subscription_request is invoked.


A complete tutorial can be found at : Registration tutorial

Typedef Documentation

Enum describing remote friend status

typedef struct _LinphoneFriend LinphoneFriend

Represents a buddy, all presence actions like subscription and status change notification are performed on this object

Enumeration Type Documentation

Enum controlling behavior for incoming subscription request.
Use by linphone_friend_set_inc_subscribe_policy()

Enumerator
LinphoneSPWait 

Does not automatically accept an incoming subscription request. This policy implies that a decision has to be taken for each incoming subscription request notified by callback LinphoneCoreVTable.new_subscription_request

LinphoneSPDeny 

Rejects incoming subscription request.

LinphoneSPAccept 

Automatically accepts a subscription request.

Enum describing remote friend status

Enumerator
LinphoneStatusOffline 

Offline

LinphoneStatusOnline 

Online

LinphoneStatusBusy 

Busy

LinphoneStatusBeRightBack 

Be right back

LinphoneStatusAway 

Away

LinphoneStatusOnThePhone 

On the phone

LinphoneStatusOutToLunch 

Out to lunch

LinphoneStatusDoNotDisturb 

Do not disturb

LinphoneStatusMoved 

Moved in this sate, call can be redirected if an alternate contact address has been set using function linphone_core_set_presence_info()

LinphoneStatusAltService 

Using another messaging service

LinphoneStatusPending 

Pending

Function Documentation

LinphoneFriend* linphone_friend_new ( )

Contructor

Returns
a new empty LinphoneFriend
LinphoneFriend* linphone_friend_new_with_addr ( const char *  addr)

Contructor same as linphone_friend_new() + linphone_friend_set_addr()

Parameters
addra buddy address, must be a sip uri like sip:joe@s.nosp@m.ip.l.nosp@m.inpho.nosp@m.ne.o.nosp@m.rg
Returns
a new LinphoneFriend with address initialized
void linphone_friend_destroy ( LinphoneFriend lf)

Destructor

Parameters
lfLinphoneFriend object
int linphone_friend_set_addr ( LinphoneFriend fr,
const LinphoneAddress address 
)

set LinphoneAddress for this friend

Parameters
frLinphoneFriend object
addressLinphoneAddress
int linphone_friend_set_name ( LinphoneFriend lf,
const char *  name 
)

set the display name for this friend

Parameters
lfLinphoneFriend object
name
const LinphoneAddress* linphone_friend_get_address ( const LinphoneFriend lf)

get address of this friend

Parameters
lfLinphoneFriend object
Returns
LinphoneAddress
bool_t linphone_friend_subscribes_enabled ( const LinphoneFriend lf)

get subscription flag value

Parameters
lfLinphoneFriend object
Returns
returns true is subscription is activated for this friend
int linphone_friend_enable_subscribes ( LinphoneFriend fr,
bool_t  val 
)

Configure LinphoneFriend to subscribe to presence information

Parameters
frLinphoneFriend object
valif TRUE this friend will receive subscription message
int linphone_friend_set_inc_subscribe_policy ( LinphoneFriend fr,
LinphoneSubscribePolicy  pol 
)

Configure incoming subscription policy for this friend.

Parameters
frLinphoneFriend object
polLinphoneSubscribePolicy policy to apply.
LinphoneSubscribePolicy linphone_friend_get_inc_subscribe_policy ( const LinphoneFriend lf)

get current subscription policy for this LinphoneFriend

Parameters
lfLinphoneFriend object
Returns
LinphoneSubscribePolicy
void linphone_friend_edit ( LinphoneFriend fr)

Starts editing a friend configuration.

Because friend configuration must be consistent, applications MUST call linphone_friend_edit() before doing any attempts to modify friend configuration (such as address or subscription policy and so on). Once the modifications are done, then the application must call linphone_friend_done() to commit the changes.

void linphone_friend_done ( LinphoneFriend fr)

Commits modification made to the friend configuration.

Parameters
frLinphoneFriend object
LinphoneOnlineStatus linphone_friend_get_status ( const LinphoneFriend lf)

get friend status

Returns
LinphoneOnlineStatus
const char* linphone_online_status_to_string ( LinphoneOnlineStatus  ss)

return humain readable presence status

Parameters
ss
void linphone_core_set_presence_info ( LinphoneCore lc,
int  minutes_away,
const char *  alternative_contact,
LinphoneOnlineStatus  os 
)

Set my presence status

Parameters
lcLinphoneCore object
minutes_awayhow long in away
alternative_contactsip uri used to redirect call in state LinphoneStatusMoved
osLinphoneOnlineStatus
LinphoneOnlineStatus linphone_core_get_presence_info ( const LinphoneCore lc)

get my presence status

Parameters
lcLinphoneCore object
Returns
LinphoneOnlineStatus
void linphone_core_add_friend ( LinphoneCore lc,
LinphoneFriend fr 
)

Add a friend to the current buddy list, if subscription attribute is set, a SIP SUBSCRIBE message is sent.

Parameters
lcLinphoneCore object
frLinphoneFriend to add
void linphone_core_remove_friend ( LinphoneCore lc,
LinphoneFriend fr 
)

remove a friend from the buddy list

Parameters
lcLinphoneCore object
frLinphoneFriend to add
void linphone_core_reject_subscriber ( LinphoneCore lc,
LinphoneFriend lf 
)

Black list a friend. same as linphone_friend_set_inc_subscribe_policy() with LinphoneSPDeny policy;

Parameters
lcLinphoneCore object
lfLinphoneFriend to add
const MSList* linphone_core_get_friend_list ( const LinphoneCore lc)

get Buddy list of LinphoneFriend

Parameters
lcLinphoneCore object
void linphone_core_notify_all_friends ( LinphoneCore lc,
LinphoneOnlineStatus  os 
)

notify all friends that have subscribed

Parameters
lcLinphoneCore object
osLinphoneOnlineStatus to notify