# Managing Buddies and buddy list and presence

## 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
LinphoneFriend * | linphone_friend_new ()
LinphoneFriend * | linphone_friend_new_with_addr (const char *addr)
void | linphone_friend_destroy (LinphoneFriend *lf)
int | linphone_friend_set_addr (LinphoneFriend *fr, const LinphoneAddress *address)
const LinphoneAddress * | linphone_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_online_status_to_string(linphone_friend_get_status(friend))
                                    ,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

typedef enum _LinphoneOnlineStatus LinphoneOnlineStatus

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

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

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:

  | addr | a buddy address, must be a sip uri like sip:joe@sip.linphone.org

Returns:
  a new LinphoneFriend with address initialized

void linphone_friend_destroy | ( | LinphoneFriend * | lf | ) |

Destructor

Parameters:

  | lf | LinphoneFriend object

int linphone_friend_set_addr | ( | LinphoneFriend * | fr,
|  | const LinphoneAddress * | address |
| ) |  |  |

set LinphoneAddress for this friend

Parameters:

  | fr | LinphoneFriend object
  | address | LinphoneAddress

const LinphoneAddress* linphone_friend_get_address | ( | const LinphoneFriend * | lf | ) |

get address of this friend

Parameters:

  | lf | LinphoneFriend object

Returns:
  LinphoneAddress

bool_t linphone_friend_subscribes_enabled | ( | const LinphoneFriend * | lf | ) |

get subscription flag value

Parameters:

  | lf | LinphoneFriend 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:

  | fr | LinphoneFriend object
  | val | if 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:

  | fr | LinphoneFriend object
  | pol | LinphoneSubscribePolicy policy to apply.

LinphoneSubscribePolicy linphone_friend_get_inc_subscribe_policy | ( | const LinphoneFriend * | lf | ) |

get current subscription policy for this LinphoneFriend

Parameters:

  | lf | LinphoneFriend 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:

  | fr | LinphoneFriend 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:

  | lc | LinphoneCore object
  | minutes_away | how long in away
  | alternative_contact | sip uri used to redirect call in state LinphoneStatusMoved
  | os | LinphoneOnlineStatus

LinphoneOnlineStatus linphone_core_get_presence_info | ( | const LinphoneCore * | lc | ) |

get my presence status

Parameters:

  | lc | LinphoneCore 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:

  | lc | LinphoneCore object
  | fr | LinphoneFriend to add

void linphone_core_remove_friend | ( | LinphoneCore * | lc,
|  | LinphoneFriend * | fr |
| ) |  |  |

remove a friend from the buddy list

Parameters:

  | lc | LinphoneCore object
  | fr | LinphoneFriend 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:

  | lc | LinphoneCore object
  | lf | LinphoneFriend to add

const MSList* linphone_core_get_friend_list | ( | const LinphoneCore * | lc | ) |

get Buddy list of LinphoneFriend

Parameters:

  | lc | LinphoneCore object

void linphone_core_notify_all_friends | ( | LinphoneCore * | lc,
|  | LinphoneOnlineStatus | os |
| ) |  |  |

notify all friends that have subscribed

Parameters:

  | lc | LinphoneCore object
  | os | LinphoneOnlineStatus to notify