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

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:
More...

Typedefs

typedef enum _LinphoneOnlineStatus LinphoneOnlineStatus
 
typedef struct _LinphoneFriend LinphoneFriend
 

Enumerations

enum  LinphoneSubscribePolicy {
  LinphoneSPWait,
  LinphoneSPDeny,
  LinphoneSPAccept
}
 
enum  _LinphoneOnlineStatus {
  LinphoneStatusOffline,
  LinphoneStatusOnline,
  LinphoneStatusBusy,
  LinphoneStatusBeRightBack,
  LinphoneStatusAway,
  LinphoneStatusOnThePhone,
  LinphoneStatusOutToLunch,
  LinphoneStatusDoNotDisturb,
  LinphoneStatusMoved,
  LinphoneStatusAltService,
  LinphoneStatusPending
}
 

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

◆ LinphoneOnlineStatus

Enum describing remote friend status

◆ LinphoneFriend

typedef struct _LinphoneFriend LinphoneFriend

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

Enumeration Type Documentation

◆ LinphoneSubscribePolicy

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.

◆ _LinphoneOnlineStatus

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

◆ linphone_friend_new()

LinphoneFriend* linphone_friend_new ( )

Contructor

Returns
a new empty LinphoneFriend

◆ linphone_friend_new_with_addr()

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

◆ linphone_friend_destroy()

void linphone_friend_destroy ( LinphoneFriend lf)

Destructor

Parameters
lfLinphoneFriend object

◆ linphone_friend_set_addr()

int linphone_friend_set_addr ( LinphoneFriend fr,
const LinphoneAddress address 
)

set LinphoneAddress for this friend

Parameters
frLinphoneFriend object
addressLinphoneAddress

◆ linphone_friend_set_name()

int linphone_friend_set_name ( LinphoneFriend lf,
const char *  name 
)

set the display name for this friend

Parameters
lfLinphoneFriend object
name

◆ linphone_friend_get_address()

const LinphoneAddress* linphone_friend_get_address ( const LinphoneFriend lf)

get address of this friend

Parameters
lfLinphoneFriend object
Returns
LinphoneAddress

◆ linphone_friend_subscribes_enabled()

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

◆ linphone_friend_enable_subscribes()

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

◆ linphone_friend_set_inc_subscribe_policy()

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.

◆ linphone_friend_get_inc_subscribe_policy()

LinphoneSubscribePolicy linphone_friend_get_inc_subscribe_policy ( const LinphoneFriend lf)

get current subscription policy for this LinphoneFriend

Parameters
lfLinphoneFriend object
Returns
LinphoneSubscribePolicy

◆ linphone_friend_edit()

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.

◆ linphone_friend_done()

void linphone_friend_done ( LinphoneFriend fr)

Commits modification made to the friend configuration.

Parameters
frLinphoneFriend object

◆ linphone_friend_get_status()

LinphoneOnlineStatus linphone_friend_get_status ( const LinphoneFriend lf)

get friend status

Returns
LinphoneOnlineStatus

◆ linphone_online_status_to_string()

const char* linphone_online_status_to_string ( LinphoneOnlineStatus  ss)

return humain readable presence status

Parameters
ss

◆ linphone_core_set_presence_info()

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

◆ linphone_core_get_presence_info()

LinphoneOnlineStatus linphone_core_get_presence_info ( const LinphoneCore lc)

get my presence status

Parameters
lcLinphoneCore object
Returns
LinphoneOnlineStatus

◆ linphone_core_add_friend()

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

◆ linphone_core_remove_friend()

void linphone_core_remove_friend ( LinphoneCore lc,
LinphoneFriend fr 
)

remove a friend from the buddy list

Parameters
lcLinphoneCore object
frLinphoneFriend to add

◆ linphone_core_reject_subscriber()

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

◆ linphone_core_get_friend_list()

const MSList* linphone_core_get_friend_list ( const LinphoneCore lc)

get Buddy list of LinphoneFriend

Parameters
lcLinphoneCore object

◆ linphone_core_notify_all_friends()

void linphone_core_notify_all_friends ( LinphoneCore lc,
LinphoneOnlineStatus  os 
)

notify all friends that have subscribed

Parameters
lcLinphoneCore object
osLinphoneOnlineStatus to notify
linphone_friend_edit
void linphone_friend_edit(LinphoneFriend *fr)
Definition: friend.c:369
linphone_friend_new_with_addr
LinphoneFriend * linphone_friend_new_with_addr(const char *addr)
Definition: friend.c:153
linphone_address_as_string
char * linphone_address_as_string(const LinphoneAddress *u)
Definition: address.c:120
linphone_friend_done
void linphone_friend_done(LinphoneFriend *fr)
Definition: friend.c:372
linphone_friend_get_status
LinphoneOnlineStatus linphone_friend_get_status(const LinphoneFriend *lf)
Definition: friend.c:326
linphone_friend_enable_subscribes
int linphone_friend_enable_subscribes(LinphoneFriend *fr, bool_t val)
Definition: friend.c:223
linphone_online_status_to_string
const char * linphone_online_status_to_string(LinphoneOnlineStatus ss)
Definition: friend.c:29
LinphoneSPAccept
@ LinphoneSPAccept
Definition: linphonefriend.h:48
linphone_friend_set_inc_subscribe_policy
int linphone_friend_set_inc_subscribe_policy(LinphoneFriend *fr, LinphoneSubscribePolicy pol)
Definition: friend.c:228
LinphoneAddress
struct SalAddress LinphoneAddress
Definition: linphonecore.h:89
LinphoneFriend
struct _LinphoneFriend LinphoneFriend
Definition: linphonefriend.h:108
linphone_friend_get_address
const LinphoneAddress * linphone_friend_get_address(const LinphoneFriend *lf)
Definition: friend.c:314