linphonefriend.h 18.3 KB
Newer Older
jehan's avatar
jehan committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
/*
linphonefriend.h
Copyright (C) 2010  Belledonne Communications SARL

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
17
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
jehan's avatar
jehan committed
18 19 20 21
*/

#ifndef LINPHONEFRIEND_H_
#define LINPHONEFRIEND_H_
22 23

#include "linphonepresence.h"
24
#include "vcard.h"
25

jehan's avatar
jehan committed
26 27 28
#ifdef __cplusplus
extern "C" {
#endif
29

jehan's avatar
jehan committed
30 31 32 33 34 35 36 37
/**
 * @addtogroup buddy_list
 * @{
 */
/**
 * Enum controlling behavior for incoming subscription request.
 * <br> Use by linphone_friend_set_inc_subscribe_policy()
 */
38
typedef enum _LinphoneSubscribePolicy {
jehan's avatar
jehan committed
39 40
	/**
	 * Does not automatically accept an incoming subscription request.
41
	 * This policy implies that a decision has to be taken for each incoming subscription request notified by callback LinphoneCoreVTable.new_subscription_requested
jehan's avatar
jehan committed
42 43 44 45 46 47 48 49 50 51 52
	 *
	 */
	LinphoneSPWait,
	/**
	 * Rejects incoming subscription request.
	 */
	LinphoneSPDeny,
	/**
	 * Automatically accepts a subscription request.
	 */
	LinphoneSPAccept
53
} LinphoneSubscribePolicy;
jehan's avatar
jehan committed
54 55 56

/**
 * Enum describing remote friend status
57
 * @deprecated Use #LinphonePresenceModel and #LinphonePresenceActivity instead
jehan's avatar
jehan committed
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
 */
typedef enum _LinphoneOnlineStatus{
	/**
	 * Offline
	 */
	LinphoneStatusOffline,
	/**
	 * Online
	 */
	LinphoneStatusOnline,
	/**
	 * Busy
	 */
	LinphoneStatusBusy,
	/**
	 * Be right back
	 */
	LinphoneStatusBeRightBack,
	/**
	 * Away
	 */
	LinphoneStatusAway,
	/**
	 * On the phone
	 */
	LinphoneStatusOnThePhone,
	/**
	 * Out to lunch
	 */
	LinphoneStatusOutToLunch,
	/**
	 * Do not disturb
	 */
	LinphoneStatusDoNotDisturb,
	/**
	 * Moved in this sate, call can be redirected if an alternate contact address has been set using function linphone_core_set_presence_info()
	 */
	LinphoneStatusMoved,
	/**
	 * Using another messaging service
	 */
	LinphoneStatusAltService,
	/**
	 * Pending
	 */
	LinphoneStatusPending,
104 105 106 107
	/**
	 * Vacation
	 */
	LinphoneStatusVacation,
Simon Morlat's avatar
Simon Morlat committed
108

jehan's avatar
jehan committed
109 110 111 112 113 114 115 116 117 118 119 120 121
	LinphoneStatusEnd
}LinphoneOnlineStatus;


struct _LinphoneFriend;
/**
 * Represents a buddy, all presence actions like subscription and status change notification are performed on this object
 */
typedef struct _LinphoneFriend LinphoneFriend;

/**
 * Contructor
 * @return a new empty #LinphoneFriend
122
 * @deprecated use #linphone_core_create_friend instead
jehan's avatar
jehan committed
123
 */
jehan's avatar
jehan committed
124
LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneFriend * linphone_friend_new(void);
Ghislain MARY's avatar
Ghislain MARY committed
125

jehan's avatar
jehan committed
126
/**
Ghislain MARY's avatar
Ghislain MARY committed
127
 * Contructor same as linphone_friend_new() + linphone_friend_set_address()
jehan's avatar
jehan committed
128 129
 * @param addr a buddy address, must be a sip uri like sip:joe@sip.linphone.org
 * @return a new #LinphoneFriend with \link linphone_friend_get_address() address initialized \endlink
130
 * @deprecated use #linphone_core_create_friend_with_address instead
jehan's avatar
jehan committed
131
 */
jehan's avatar
jehan committed
132
LINPHONE_PUBLIC	LINPHONE_DEPRECATED LinphoneFriend *linphone_friend_new_with_address(const char *addr);
Ghislain MARY's avatar
Ghislain MARY committed
133 134 135 136 137 138

/**
 * Contructor same as linphone_friend_new() + linphone_friend_set_address()
 * @deprecated Use #linphone_friend_new_with_address instead
 */
#define linphone_friend_new_with_addr linphone_friend_new_with_address
jehan's avatar
jehan committed
139

jehan's avatar
jehan committed
140
/**
141 142 143
 * Destroy a LinphoneFriend.
 * @param lf LinphoneFriend object
 * @deprecated Use linphone_friend_unref() instead.
jehan's avatar
jehan committed
144
 */
Ghislain MARY's avatar
Ghislain MARY committed
145
LINPHONE_PUBLIC void linphone_friend_destroy(LinphoneFriend *lf);
jehan's avatar
jehan committed
146

jehan's avatar
jehan committed
147
/**
148
 * Set #LinphoneAddress for this friend
jehan's avatar
jehan committed
149
 * @param fr #LinphoneFriend object
jehan's avatar
jehan committed
150 151
 * @param address #LinphoneAddress
 */
152 153 154 155 156 157 158
LINPHONE_PUBLIC int linphone_friend_set_address(LinphoneFriend *fr, const LinphoneAddress* address);

/**
 * Set #LinphoneAddress for this friend
 * @deprecated Use #linphone_friend_set_address instead
 */
#define linphone_friend_set_addr linphone_friend_set_address
jehan's avatar
jehan committed
159

160
/**
161 162 163 164
 * Get address of this friend
 * @param lf #LinphoneFriend object
 * @return #LinphoneAddress
 */
165
LINPHONE_PUBLIC LinphoneAddress * linphone_friend_get_address(const LinphoneFriend *lf);
166 167 168 169 170 171 172 173 174 175 176 177 178

/**
 * Adds an address in this friend
 * @param lf #LinphoneFriend object
 * @param addr #LinphoneAddress object
 */
LINPHONE_PUBLIC void linphone_friend_add_address(LinphoneFriend *lf, const LinphoneAddress *addr);

/**
 * Returns a list of #LinphoneAddress for this friend
 * @param lf #LinphoneFriend object
 * @return \mslist{LinphoneAddress}
 */
179
LINPHONE_PUBLIC bctbx_list_t* linphone_friend_get_addresses(LinphoneFriend *lf);
180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197

/**
 * Removes an address in this friend
 * @param lf #LinphoneFriend object
 * @param addr #LinphoneAddress object
 */
LINPHONE_PUBLIC void linphone_friend_remove_address(LinphoneFriend *lf, const LinphoneAddress *addr);

/**
 * Adds a phone number in this friend
 * @param lf #LinphoneFriend object
 * @param phone number to add
 */
LINPHONE_PUBLIC void linphone_friend_add_phone_number(LinphoneFriend *lf, const char *phone);

/**
 * Returns a list of phone numbers for this friend
 * @param lf #LinphoneFriend object
198
 * @return \mslist{const char *}
199
 */
200
LINPHONE_PUBLIC bctbx_list_t* linphone_friend_get_phone_numbers(LinphoneFriend *lf);
201 202 203 204 205 206 207

/**
 * Removes a phone number in this friend
 * @param lf #LinphoneFriend object
 * @param phone number to remove
 */
LINPHONE_PUBLIC void linphone_friend_remove_phone_number(LinphoneFriend *lf, const char *phone);
208 209 210

/**
 * Set the display name for this friend
211 212 213
 * @param lf #LinphoneFriend object
 * @param name 
 */
Ghislain MARY's avatar
Ghislain MARY committed
214
LINPHONE_PUBLIC int linphone_friend_set_name(LinphoneFriend *lf, const char *name);
215

jehan's avatar
jehan committed
216
/**
217
 * Get the display name for this friend
jehan's avatar
jehan committed
218
 * @param lf #LinphoneFriend object
219
 * @return The display name of this friend
jehan's avatar
jehan committed
220
 */
221 222
LINPHONE_PUBLIC const char * linphone_friend_get_name(const LinphoneFriend *lf);

jehan's avatar
jehan committed
223 224 225 226
/**
 * get subscription flag value
 * @param lf #LinphoneFriend object
 * @return returns true is subscription is activated for this friend
jehan's avatar
jehan committed
227 228
 *
 */
Ghislain MARY's avatar
Ghislain MARY committed
229
LINPHONE_PUBLIC bool_t linphone_friend_subscribes_enabled(const LinphoneFriend *lf);
jehan's avatar
jehan committed
230 231
#define linphone_friend_get_send_subscribe linphone_friend_subscribes_enabled

jehan's avatar
jehan committed
232 233 234 235 236 237
/**
 * Configure #LinphoneFriend to subscribe to presence information
 * @param fr #LinphoneFriend object
 * @param val if TRUE this friend will receive subscription message
 */

238
LINPHONE_PUBLIC	int linphone_friend_enable_subscribes(LinphoneFriend *fr, bool_t val);
jehan's avatar
jehan committed
239
#define linphone_friend_send_subscribe linphone_friend_enable_subscribes
Ghislain MARY's avatar
Ghislain MARY committed
240

jehan's avatar
jehan committed
241 242 243 244 245
/**
 * Configure incoming subscription policy for this friend.
 * @param fr #LinphoneFriend object
 * @param pol #LinphoneSubscribePolicy policy to apply.
 */
Ghislain MARY's avatar
Ghislain MARY committed
246
LINPHONE_PUBLIC int linphone_friend_set_inc_subscribe_policy(LinphoneFriend *fr, LinphoneSubscribePolicy pol);
Ghislain MARY's avatar
Ghislain MARY committed
247

jehan's avatar
jehan committed
248 249 250 251 252 253
/**
 * get current subscription policy for this #LinphoneFriend
 * @param lf #LinphoneFriend object
 * @return #LinphoneSubscribePolicy
 *
 */
Ghislain MARY's avatar
Ghislain MARY committed
254
LINPHONE_PUBLIC LinphoneSubscribePolicy linphone_friend_get_inc_subscribe_policy(const LinphoneFriend *lf);
jehan's avatar
jehan committed
255

jehan's avatar
jehan committed
256 257 258 259 260
/**
 * Starts editing a friend configuration.
 *
 * Because friend configuration must be consistent, applications MUST
 * call linphone_friend_edit() before doing any attempts to modify
Ghislain MARY's avatar
Ghislain MARY committed
261
 * friend configuration (such as \link linphone_friend_set_address() address \endlink  or \link linphone_friend_set_inc_subscribe_policy() subscription policy\endlink  and so on).
jehan's avatar
jehan committed
262 263 264
 * Once the modifications are done, then the application must call
 * linphone_friend_done() to commit the changes.
**/
265
LINPHONE_PUBLIC	void linphone_friend_edit(LinphoneFriend *fr);
Ghislain MARY's avatar
Ghislain MARY committed
266

jehan's avatar
jehan committed
267 268 269 270
/**
 * Commits modification made to the friend configuration.
 * @param fr #LinphoneFriend object
**/
271
LINPHONE_PUBLIC	void linphone_friend_done(LinphoneFriend *fr);
jehan's avatar
jehan committed
272

jehan's avatar
jehan committed
273
/**
274
 * Get the status of a friend
275
 * @param[in] lf A #LinphoneFriend object
jehan's avatar
jehan committed
276
 * @return #LinphoneOnlineStatus
277
 * @deprecated Use linphone_friend_get_presence_model() instead
jehan's avatar
jehan committed
278
 */
Ghislain MARY's avatar
Ghislain MARY committed
279
LINPHONE_PUBLIC LinphoneOnlineStatus linphone_friend_get_status(const LinphoneFriend *lf);
280

281 282 283 284 285 286 287
/**
 * Get subscription state of a friend
 * @param[in] lf A #LinphoneFriend object
 * @return #LinphoneSubscriptionState
 */

LINPHONE_PUBLIC LinphoneSubscriptionState linphone_friend_get_subscription_state(const LinphoneFriend *lf);
288

289
/**
290
 * Get the presence model of a friend
291
 * @param[in] lf A #LinphoneFriend object
Ghislain MARY's avatar
Ghislain MARY committed
292
 * @return A #LinphonePresenceModel object, or NULL if the friend do not have presence information (in which case he is considered offline)
293
 */
294 295 296 297 298 299 300 301 302
LINPHONE_PUBLIC const LinphonePresenceModel * linphone_friend_get_presence_model(const LinphoneFriend *lf);

/**
 * Get the presence model for a specific SIP URI or phone number of a friend
 * @param[in] lf A #LinphoneFriend object
 * @param[in] uri_or_tel The SIP URI or phone number for which to get the presence model
 * @return A #LinphonePresenceModel object, or NULL if the friend do not have presence information for this SIP URI or phone number
 */
LINPHONE_PUBLIC const LinphonePresenceModel * linphone_friend_get_presence_model_for_uri_or_tel(const LinphoneFriend *lf, const char *uri_or_tel);
303

304 305 306 307 308 309 310
/**
 * Set the presence model of a friend
 * @param[in] lf A #LinphoneFriend object
 * @param[in] presence The #LinphonePresenceModel object to set for the friend
 */
LINPHONE_PUBLIC void linphone_friend_set_presence_model(LinphoneFriend *lf, LinphonePresenceModel *presence);

311 312 313 314 315 316 317 318
/**
 * Set the presence model for a specific SIP URI or phone number of a friend
 * @param[in] lf A #LinphoneFriend object
 * @param[in] uri_or_tel The SIP URI or phone number for which to set the presence model
 * @param[in] presence The #LinphonePresenceModel object to set
 */
LINPHONE_PUBLIC void linphone_friend_set_presence_model_for_uri_or_tel(LinphoneFriend *lf, const char *uri_or_tel, LinphonePresenceModel *presence);

319 320 321 322 323 324 325
/**
 * Tells whether we already received presence information for a friend.
 * @param[in] lf A #LinphoneFriend object
 * @return TRUE if presence information has been received for the friend, FALSE otherwise.
 */
LINPHONE_PUBLIC bool_t linphone_friend_is_presence_received(const LinphoneFriend *lf);

Simon Morlat's avatar
Simon Morlat committed
326 327 328 329 330 331 332 333 334 335
/**
 * Store user pointer to friend object.
**/
LINPHONE_PUBLIC void linphone_friend_set_user_data(LinphoneFriend *lf, void *data);

/**
 * Retrieve user data associated with friend.
**/
LINPHONE_PUBLIC void* linphone_friend_get_user_data(const LinphoneFriend *lf);

Ghislain MARY's avatar
Ghislain MARY committed
336
LINPHONE_PUBLIC BuddyInfo * linphone_friend_get_info(const LinphoneFriend *lf);
Ghislain MARY's avatar
Ghislain MARY committed
337 338 339 340 341 342

/**
 * Set the reference key of a friend.
 * @param[in] lf #LinphoneFriend object.
 * @param[in] key The reference key to use for the friend.
**/
Ghislain MARY's avatar
Ghislain MARY committed
343
LINPHONE_PUBLIC void linphone_friend_set_ref_key(LinphoneFriend *lf, const char *key);
Ghislain MARY's avatar
Ghislain MARY committed
344 345 346 347

/**
 * Get the reference key of a friend.
 * @param[in] lf #LinphoneFriend object.
348
 * @return The reference key of the friend.
Ghislain MARY's avatar
Ghislain MARY committed
349
**/
Ghislain MARY's avatar
Ghislain MARY committed
350
LINPHONE_PUBLIC const char *linphone_friend_get_ref_key(const LinphoneFriend *lf);
Ghislain MARY's avatar
Ghislain MARY committed
351 352 353 354

/**
 * Check that the given friend is in a friend list.
 * @param[in] lf #LinphoneFriend object.
355
 * @return TRUE if the friend is in a friend list, FALSE otherwise.
Ghislain MARY's avatar
Ghislain MARY committed
356
**/
Ghislain MARY's avatar
Ghislain MARY committed
357
LINPHONE_PUBLIC bool_t linphone_friend_in_list(const LinphoneFriend *lf);
jehan's avatar
jehan committed
358 359


jehan's avatar
jehan committed
360
/**
361
 * Return humain readable presence status
jehan's avatar
jehan committed
362
 * @param ss
363
 * @deprecated Use #LinphonePresenceModel, #LinphonePresenceActivity and linphone_presence_activity_to_string() instead.
jehan's avatar
jehan committed
364
 */
Ghislain MARY's avatar
Ghislain MARY committed
365
LINPHONE_PUBLIC const char *linphone_online_status_to_string(LinphoneOnlineStatus ss);
jehan's avatar
jehan committed
366 367


jehan's avatar
jehan committed
368
/**
369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384
 * Create a default LinphoneFriend.
 * @param[in] lc #LinphoneCore object
 * @return The created #LinphoneFriend object
 */
LINPHONE_PUBLIC LinphoneFriend * linphone_core_create_friend(LinphoneCore *lc);

/**
 * Create a LinphoneFriend from the given address.
 * @param[in] lc #LinphoneCore object
 * @param[in] address A string containing the address to create the LinphoneFriend from
 * @return The created #LinphoneFriend object
 */
LINPHONE_PUBLIC LinphoneFriend * linphone_core_create_friend_with_address(LinphoneCore *lc, const char *address);

/**
 * Set my presence status
385 386 387 388 389
 * @param[in] lc #LinphoneCore object
 * @param[in] minutes_away how long in away
 * @param[in] alternative_contact sip uri used to redirect call in state #LinphoneStatusMoved
 * @param[in] os #LinphoneOnlineStatus
 * @deprecated Use linphone_core_set_presence_model() instead
jehan's avatar
jehan committed
390
 */
391
LINPHONE_PUBLIC void linphone_core_set_presence_info(LinphoneCore *lc,int minutes_away,const char *alternative_contact,LinphoneOnlineStatus os);
392 393

/**
394
 * Set my presence model
395 396
 * @param[in] lc #LinphoneCore object
 * @param[in] presence #LinphonePresenceModel
397
 */
398
LINPHONE_PUBLIC void linphone_core_set_presence_model(LinphoneCore *lc, LinphonePresenceModel *presence);
399

jehan's avatar
jehan committed
400
/**
401
 * Get my presence status
402
 * @param[in] lc #LinphoneCore object
jehan's avatar
jehan committed
403
 * @return #LinphoneOnlineStatus
404
 * @deprecated Use linphone_core_get_presence_model() instead
jehan's avatar
jehan committed
405
 */
Ghislain MARY's avatar
Ghislain MARY committed
406
LINPHONE_PUBLIC LinphoneOnlineStatus linphone_core_get_presence_info(const LinphoneCore *lc);
jehan's avatar
jehan committed
407

408
/**
409
 * Get my presence model
410 411
 * @param[in] lc #LinphoneCore object
 * @return A #LinphonePresenceModel object, or NULL if no presence model has been set.
412
 */
Ghislain MARY's avatar
Ghislain MARY committed
413
LINPHONE_PUBLIC LinphonePresenceModel * linphone_core_get_presence_model(const LinphoneCore *lc);
414

Ghislain MARY's avatar
Ghislain MARY committed
415 416 417
/**
 * @deprecated Use linphone_core_interpret_url() instead
 */
Ghislain MARY's avatar
Ghislain MARY committed
418
LINPHONE_PUBLIC void linphone_core_interpret_friend_uri(LinphoneCore *lc, const char *uri, char **result);
Ghislain MARY's avatar
Ghislain MARY committed
419

jehan's avatar
jehan committed
420 421 422 423
/**
 * Add a friend to the current buddy list, if \link linphone_friend_enable_subscribes() subscription attribute \endlink is set, a SIP SUBSCRIBE message is sent.
 * @param lc #LinphoneCore object
 * @param fr #LinphoneFriend to add
424
 * @deprecated use linphone_friend_list_add_friend() instead.
jehan's avatar
jehan committed
425
 */
426
LINPHONE_PUBLIC	void linphone_core_add_friend(LinphoneCore *lc, LinphoneFriend *fr);
Ghislain MARY's avatar
Ghislain MARY committed
427

jehan's avatar
jehan committed
428
/**
429
 * Removes a friend from the buddy list
jehan's avatar
jehan committed
430
 * @param lc #LinphoneCore object
431
 * @param fr #LinphoneFriend to remove
432
 * @deprecated use linphone_friend_list_remove_friend() instead.
jehan's avatar
jehan committed
433
 */
Ghislain MARY's avatar
Ghislain MARY committed
434
LINPHONE_PUBLIC void linphone_core_remove_friend(LinphoneCore *lc, LinphoneFriend *fr);
Ghislain MARY's avatar
Ghislain MARY committed
435

jehan's avatar
jehan committed
436 437 438
/**
 * Black list a friend. same as linphone_friend_set_inc_subscribe_policy() with #LinphoneSPDeny policy;
 * @param lc #LinphoneCore object
jehan's avatar
jehan committed
439
 * @param lf #LinphoneFriend to add
jehan's avatar
jehan committed
440
 */
Ghislain MARY's avatar
Ghislain MARY committed
441
LINPHONE_PUBLIC void linphone_core_reject_subscriber(LinphoneCore *lc, LinphoneFriend *lf);
Ghislain MARY's avatar
Ghislain MARY committed
442

jehan's avatar
jehan committed
443
/**
Ghislain MARY's avatar
Ghislain MARY committed
444
 * Get Buddy list of LinphoneFriend
445 446
 * @param[in] lc #LinphoneCore object
 * @return \mslist{LinphoneFriend}
447
 * @deprecated use linphone_core_get_friends_lists() or linphone_friend_list_get_friends() instead.
Ghislain MARY's avatar
Ghislain MARY committed
448
 */
449
LINPHONE_PUBLIC	const bctbx_list_t * linphone_core_get_friend_list(const LinphoneCore *lc);
Ghislain MARY's avatar
Ghislain MARY committed
450

jehan's avatar
jehan committed
451
/**
Ghislain MARY's avatar
Ghislain MARY committed
452
 * Notify all friends that have subscribed
jehan's avatar
jehan committed
453
 * @param lc #LinphoneCore object
Ghislain MARY's avatar
Ghislain MARY committed
454
 * @param presence #LinphonePresenceModel to notify
Ghislain MARY's avatar
Ghislain MARY committed
455
 */
Ghislain MARY's avatar
Ghislain MARY committed
456
LINPHONE_PUBLIC void linphone_core_notify_all_friends(LinphoneCore *lc, LinphonePresenceModel *presence);
Ghislain MARY's avatar
Ghislain MARY committed
457

Ghislain MARY's avatar
Ghislain MARY committed
458 459 460 461
/**
 * Search a LinphoneFriend by its address.
 * @param[in] lc #LinphoneCore object.
 * @param[in] addr The address to use to search the friend.
462
 * @return The #LinphoneFriend object corresponding to the given address.
Simon Morlat's avatar
Simon Morlat committed
463
 * @deprecated use linphone_core_find_friend() instead.
Ghislain MARY's avatar
Ghislain MARY committed
464
 */
Ghislain MARY's avatar
Ghislain MARY committed
465
LINPHONE_PUBLIC LinphoneFriend *linphone_core_get_friend_by_address(const LinphoneCore *lc, const char *addr);
Ghislain MARY's avatar
Ghislain MARY committed
466

Simon Morlat's avatar
Simon Morlat committed
467 468 469 470
/**
 * Search a LinphoneFriend by its address.
 * @param[in] lc #LinphoneCore object.
 * @param[in] addr The address to use to search the friend.
471
 * @return The #LinphoneFriend object corresponding to the given address.
Simon Morlat's avatar
Simon Morlat committed
472 473 474
 */
LINPHONE_PUBLIC LinphoneFriend *linphone_core_find_friend(const LinphoneCore *lc, const LinphoneAddress *addr);

Ghislain MARY's avatar
Ghislain MARY committed
475 476 477 478
/**
 * Search a LinphoneFriend by its reference key.
 * @param[in] lc #LinphoneCore object.
 * @param[in] key The reference key to use to search the friend.
479
 * @return The #LinphoneFriend object corresponding to the given reference key.
Ghislain MARY's avatar
Ghislain MARY committed
480
 */
Ghislain MARY's avatar
Ghislain MARY committed
481
LINPHONE_PUBLIC LinphoneFriend *linphone_core_get_friend_by_ref_key(const LinphoneCore *lc, const char *key);
jehan's avatar
jehan committed
482

483 484 485 486 487 488 489 490 491
/**
 * Acquire a reference to the linphone friend.
 * @param[in] lf LinphoneFriend object
 * @return The same LinphoneFriend object
**/
LINPHONE_PUBLIC LinphoneFriend * linphone_friend_ref(LinphoneFriend *lf);

/**
 * Release a reference to the linphone friend.
492
 * @param[in] lf LinphoneFriend object
493 494
**/
LINPHONE_PUBLIC void linphone_friend_unref(LinphoneFriend *lf);
495 496 497

/**
 * Returns the LinphoneCore object managing this friend, if any.
498
 * @param[in] fr LinphoneFriend object
499 500
 */
LINPHONE_PUBLIC LinphoneCore *linphone_friend_get_core(const LinphoneFriend *fr);
501 502

/**
503
 * Returns the vCard object associated to this friend, if any
504
 * @param[in] fr LinphoneFriend object
505
 */
506
LINPHONE_PUBLIC LinphoneVcard* linphone_friend_get_vcard(LinphoneFriend *fr);
507 508

/**
509
 * Binds a vCard object to a friend
510
 * @param[in] fr LinphoneFriend object
511
 * @param[in] vcard The vCard object to bind
512
 */
513
LINPHONE_PUBLIC void linphone_friend_set_vcard(LinphoneFriend *fr, LinphoneVcard *vcard);
514 515

/**
516
 * Creates a vCard object associated to this friend if there isn't one yet and if the full name is available, either by the parameter or the one in the friend's SIP URI
517 518 519 520 521
 * @param[in] fr LinphoneFriend object
 * @param[in] name The full name of the friend or NULL to use the one from the friend's SIP URI
 * @return true if the vCard has been created, false if it wasn't possible (for exemple if name and the friend's SIP URI are null or if the friend's SIP URI doesn't have a display name), or if there is already one vcard
 */
LINPHONE_PUBLIC bool_t linphone_friend_create_vcard(LinphoneFriend *fr, const char *name);
522 523 524

/**
 * Contructor same as linphone_friend_new() + linphone_friend_set_address()
525 526
 * @param vcard a vCard object
 * @return a new #LinphoneFriend with \link linphone_friend_get_vcard() vCard initialized \endlink
527
 */
528
LINPHONE_PUBLIC	LinphoneFriend *linphone_friend_new_from_vcard(LinphoneVcard *vcard);
529

530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545
/**
 * Sets the database filename where friends will be stored.
 * If the file does not exist, it will be created.
 * @ingroup initializing
 * @param lc the linphone core
 * @param path filesystem path
**/
LINPHONE_PUBLIC void linphone_core_set_friends_database_path(LinphoneCore *lc, const char *path);

/**
 * Migrates the friends from the linphonerc to the database if not done yet
 * @ingroup initializing
 * @param lc the linphone core
**/
LINPHONE_PUBLIC void linphone_core_migrate_friends_from_rc_to_db(LinphoneCore *lc);

546 547 548 549 550 551 552
/**
 * Saves a friend either in database if configured, otherwise in linphonerc
 * @param fr the linphone friend to save
 * @param lc the linphone core
 */
void linphone_friend_save(LinphoneFriend *fr, LinphoneCore *lc);

jehan's avatar
jehan committed
553 554 555 556 557 558 559 560 561
/**
 * @}
 */

#ifdef __cplusplus
}
#endif

#endif /* LINPHONEFRIEND_H_ */