linphonefriend.h 13.7 KB
Newer Older
jehan's avatar
jehan committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
/*
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
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
*/

#ifndef LINPHONEFRIEND_H_
#define LINPHONEFRIEND_H_
22 23 24

#include "linphonepresence.h"

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

jehan's avatar
jehan committed
29 30 31 32 33 34 35 36
/**
 * @addtogroup buddy_list
 * @{
 */
/**
 * Enum controlling behavior for incoming subscription request.
 * <br> Use by linphone_friend_set_inc_subscribe_policy()
 */
37
typedef enum _LinphoneSubscribePolicy {
jehan's avatar
jehan committed
38 39
	/**
	 * Does not automatically accept an incoming subscription request.
40
	 * 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
41 42 43 44 45 46 47 48 49 50 51
	 *
	 */
	LinphoneSPWait,
	/**
	 * Rejects incoming subscription request.
	 */
	LinphoneSPDeny,
	/**
	 * Automatically accepts a subscription request.
	 */
	LinphoneSPAccept
52
} LinphoneSubscribePolicy;
jehan's avatar
jehan committed
53 54 55

/**
 * Enum describing remote friend status
56
 * @deprecated Use #LinphonePresenceModel and #LinphonePresenceActivity instead
jehan's avatar
jehan committed
57 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
 */
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,
103 104 105 106
	/**
	 * Vacation
	 */
	LinphoneStatusVacation,
Simon Morlat's avatar
Simon Morlat committed
107

jehan's avatar
jehan committed
108 109 110 111 112 113 114 115 116 117 118 119 120
	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
121
 * @deprecated use #linphone_core_create_friend instead
jehan's avatar
jehan committed
122
 */
123
LINPHONE_PUBLIC MS2_DEPRECATED LinphoneFriend * linphone_friend_new(void); /*fix me me replace MS2_DEPRECATED by LINPHONE_DEPRECATED*/
Ghislain MARY's avatar
Ghislain MARY committed
124

jehan's avatar
jehan committed
125
/**
Ghislain MARY's avatar
Ghislain MARY committed
126
 * Contructor same as linphone_friend_new() + linphone_friend_set_address()
jehan's avatar
jehan committed
127 128
 * @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
129
 * @deprecated use #linphone_core_create_friend_with_address instead
jehan's avatar
jehan committed
130
 */
131
LINPHONE_PUBLIC	MS2_DEPRECATED LinphoneFriend *linphone_friend_new_with_address(const char *addr); /*fix me me replace MS2_DEPRECATED by LINPHONE_DEPRECATED*/
Ghislain MARY's avatar
Ghislain MARY committed
132 133 134 135 136 137

/**
 * 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
138

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

jehan's avatar
jehan committed
146
/**
147
 * Set #LinphoneAddress for this friend
jehan's avatar
jehan committed
148
 * @param fr #LinphoneFriend object
jehan's avatar
jehan committed
149 150
 * @param address #LinphoneAddress
 */
151 152 153 154 155 156 157
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
158

159
/**
160 161 162 163 164 165 166 167
 * Get address of this friend
 * @param lf #LinphoneFriend object
 * @return #LinphoneAddress
 */
LINPHONE_PUBLIC	const LinphoneAddress *linphone_friend_get_address(const LinphoneFriend *lf);

/**
 * Set the display name for this friend
168 169 170
 * @param lf #LinphoneFriend object
 * @param name 
 */
Ghislain MARY's avatar
Ghislain MARY committed
171
LINPHONE_PUBLIC int linphone_friend_set_name(LinphoneFriend *lf, const char *name);
172

jehan's avatar
jehan committed
173
/**
174
 * Get the display name for this friend
jehan's avatar
jehan committed
175
 * @param lf #LinphoneFriend object
176
 * @return The display name of this friend
jehan's avatar
jehan committed
177
 */
178 179
LINPHONE_PUBLIC const char * linphone_friend_get_name(const LinphoneFriend *lf);

jehan's avatar
jehan committed
180 181 182 183
/**
 * get subscription flag value
 * @param lf #LinphoneFriend object
 * @return returns true is subscription is activated for this friend
jehan's avatar
jehan committed
184 185
 *
 */
Ghislain MARY's avatar
Ghislain MARY committed
186
LINPHONE_PUBLIC bool_t linphone_friend_subscribes_enabled(const LinphoneFriend *lf);
jehan's avatar
jehan committed
187 188
#define linphone_friend_get_send_subscribe linphone_friend_subscribes_enabled

jehan's avatar
jehan committed
189 190 191 192 193 194
/**
 * Configure #LinphoneFriend to subscribe to presence information
 * @param fr #LinphoneFriend object
 * @param val if TRUE this friend will receive subscription message
 */

195
LINPHONE_PUBLIC	int linphone_friend_enable_subscribes(LinphoneFriend *fr, bool_t val);
jehan's avatar
jehan committed
196
#define linphone_friend_send_subscribe linphone_friend_enable_subscribes
Ghislain MARY's avatar
Ghislain MARY committed
197

jehan's avatar
jehan committed
198 199 200 201 202
/**
 * Configure incoming subscription policy for this friend.
 * @param fr #LinphoneFriend object
 * @param pol #LinphoneSubscribePolicy policy to apply.
 */
Ghislain MARY's avatar
Ghislain MARY committed
203
LINPHONE_PUBLIC int linphone_friend_set_inc_subscribe_policy(LinphoneFriend *fr, LinphoneSubscribePolicy pol);
Ghislain MARY's avatar
Ghislain MARY committed
204

jehan's avatar
jehan committed
205 206 207 208 209 210
/**
 * get current subscription policy for this #LinphoneFriend
 * @param lf #LinphoneFriend object
 * @return #LinphoneSubscribePolicy
 *
 */
Ghislain MARY's avatar
Ghislain MARY committed
211
LINPHONE_PUBLIC LinphoneSubscribePolicy linphone_friend_get_inc_subscribe_policy(const LinphoneFriend *lf);
jehan's avatar
jehan committed
212

jehan's avatar
jehan committed
213 214 215 216 217
/**
 * 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
218
 * 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
219 220 221
 * Once the modifications are done, then the application must call
 * linphone_friend_done() to commit the changes.
**/
222
LINPHONE_PUBLIC	void linphone_friend_edit(LinphoneFriend *fr);
Ghislain MARY's avatar
Ghislain MARY committed
223

jehan's avatar
jehan committed
224 225 226 227
/**
 * Commits modification made to the friend configuration.
 * @param fr #LinphoneFriend object
**/
228
LINPHONE_PUBLIC	void linphone_friend_done(LinphoneFriend *fr);
jehan's avatar
jehan committed
229

jehan's avatar
jehan committed
230
/**
231
 * Get the status of a friend
232
 * @param[in] lf A #LinphoneFriend object
jehan's avatar
jehan committed
233
 * @return #LinphoneOnlineStatus
234
 * @deprecated Use linphone_friend_get_presence_model() instead
jehan's avatar
jehan committed
235
 */
Ghislain MARY's avatar
Ghislain MARY committed
236
LINPHONE_PUBLIC LinphoneOnlineStatus linphone_friend_get_status(const LinphoneFriend *lf);
237

238
/**
239
 * Get the presence model of a friend
240
 * @param[in] lf A #LinphoneFriend object
Ghislain MARY's avatar
Ghislain MARY committed
241
 * @return A #LinphonePresenceModel object, or NULL if the friend do not have presence information (in which case he is considered offline)
242
 */
Ghislain MARY's avatar
Ghislain MARY committed
243
LINPHONE_PUBLIC const LinphonePresenceModel * linphone_friend_get_presence_model(LinphoneFriend *lf);
244

245 246 247 248 249 250 251
/**
 * 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);

252 253 254 255 256 257 258
/**
 * 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
259 260 261 262 263 264 265 266 267 268
/**
 * 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
269
LINPHONE_PUBLIC BuddyInfo * linphone_friend_get_info(const LinphoneFriend *lf);
Ghislain MARY's avatar
Ghislain MARY committed
270 271 272 273 274 275

/**
 * 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
276
LINPHONE_PUBLIC void linphone_friend_set_ref_key(LinphoneFriend *lf, const char *key);
Ghislain MARY's avatar
Ghislain MARY committed
277 278 279 280

/**
 * Get the reference key of a friend.
 * @param[in] lf #LinphoneFriend object.
281
 * @return The reference key of the friend.
Ghislain MARY's avatar
Ghislain MARY committed
282
**/
Ghislain MARY's avatar
Ghislain MARY committed
283
LINPHONE_PUBLIC const char *linphone_friend_get_ref_key(const LinphoneFriend *lf);
Ghislain MARY's avatar
Ghislain MARY committed
284 285 286 287

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


jehan's avatar
jehan committed
293
/**
294
 * Return humain readable presence status
jehan's avatar
jehan committed
295
 * @param ss
296
 * @deprecated Use #LinphonePresenceModel, #LinphonePresenceActivity and linphone_presence_activity_to_string() instead.
jehan's avatar
jehan committed
297
 */
Ghislain MARY's avatar
Ghislain MARY committed
298
LINPHONE_PUBLIC const char *linphone_online_status_to_string(LinphoneOnlineStatus ss);
jehan's avatar
jehan committed
299 300


jehan's avatar
jehan committed
301
/**
302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317
 * 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
318 319 320 321 322
 * @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
323
 */
324
LINPHONE_PUBLIC void linphone_core_set_presence_info(LinphoneCore *lc,int minutes_away,const char *alternative_contact,LinphoneOnlineStatus os);
325 326

/**
327
 * Set my presence model
328 329
 * @param[in] lc #LinphoneCore object
 * @param[in] presence #LinphonePresenceModel
330
 */
331
LINPHONE_PUBLIC void linphone_core_set_presence_model(LinphoneCore *lc, LinphonePresenceModel *presence);
332

jehan's avatar
jehan committed
333
/**
334
 * Get my presence status
335
 * @param[in] lc #LinphoneCore object
jehan's avatar
jehan committed
336
 * @return #LinphoneOnlineStatus
337
 * @deprecated Use linphone_core_get_presence_model() instead
jehan's avatar
jehan committed
338
 */
Ghislain MARY's avatar
Ghislain MARY committed
339
LINPHONE_PUBLIC LinphoneOnlineStatus linphone_core_get_presence_info(const LinphoneCore *lc);
jehan's avatar
jehan committed
340

341
/**
342
 * Get my presence model
343 344
 * @param[in] lc #LinphoneCore object
 * @return A #LinphonePresenceModel object, or NULL if no presence model has been set.
345
 */
Ghislain MARY's avatar
Ghislain MARY committed
346
LINPHONE_PUBLIC LinphonePresenceModel * linphone_core_get_presence_model(const LinphoneCore *lc);
347

Ghislain MARY's avatar
Ghislain MARY committed
348 349 350
/**
 * @deprecated Use linphone_core_interpret_url() instead
 */
Ghislain MARY's avatar
Ghislain MARY committed
351
LINPHONE_PUBLIC void linphone_core_interpret_friend_uri(LinphoneCore *lc, const char *uri, char **result);
Ghislain MARY's avatar
Ghislain MARY committed
352

jehan's avatar
jehan committed
353 354 355 356 357
/**
 * 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
 */
358
LINPHONE_PUBLIC	void linphone_core_add_friend(LinphoneCore *lc, LinphoneFriend *fr);
Ghislain MARY's avatar
Ghislain MARY committed
359

jehan's avatar
jehan committed
360 361 362 363 364
/**
 * remove a friend from the buddy list
 * @param lc #LinphoneCore object
 * @param fr #LinphoneFriend to add
 */
Ghislain MARY's avatar
Ghislain MARY committed
365
LINPHONE_PUBLIC void linphone_core_remove_friend(LinphoneCore *lc, LinphoneFriend *fr);
Ghislain MARY's avatar
Ghislain MARY committed
366

jehan's avatar
jehan committed
367 368 369
/**
 * Black list a friend. same as linphone_friend_set_inc_subscribe_policy() with #LinphoneSPDeny policy;
 * @param lc #LinphoneCore object
jehan's avatar
jehan committed
370
 * @param lf #LinphoneFriend to add
jehan's avatar
jehan committed
371
 */
Ghislain MARY's avatar
Ghislain MARY committed
372
LINPHONE_PUBLIC void linphone_core_reject_subscriber(LinphoneCore *lc, LinphoneFriend *lf);
Ghislain MARY's avatar
Ghislain MARY committed
373

jehan's avatar
jehan committed
374
/**
Ghislain MARY's avatar
Ghislain MARY committed
375
 * Get Buddy list of LinphoneFriend
376 377
 * @param[in] lc #LinphoneCore object
 * @return \mslist{LinphoneFriend}
Ghislain MARY's avatar
Ghislain MARY committed
378
 */
379
LINPHONE_PUBLIC	const MSList * linphone_core_get_friend_list(const LinphoneCore *lc);
Ghislain MARY's avatar
Ghislain MARY committed
380

jehan's avatar
jehan committed
381
/**
Ghislain MARY's avatar
Ghislain MARY committed
382
 * Notify all friends that have subscribed
jehan's avatar
jehan committed
383
 * @param lc #LinphoneCore object
Ghislain MARY's avatar
Ghislain MARY committed
384
 * @param presence #LinphonePresenceModel to notify
Ghislain MARY's avatar
Ghislain MARY committed
385
 */
Ghislain MARY's avatar
Ghislain MARY committed
386
LINPHONE_PUBLIC void linphone_core_notify_all_friends(LinphoneCore *lc, LinphonePresenceModel *presence);
Ghislain MARY's avatar
Ghislain MARY committed
387

Ghislain MARY's avatar
Ghislain MARY committed
388 389 390 391
/**
 * Search a LinphoneFriend by its address.
 * @param[in] lc #LinphoneCore object.
 * @param[in] addr The address to use to search the friend.
392
 * @return The #LinphoneFriend object corresponding to the given address.
Simon Morlat's avatar
Simon Morlat committed
393
 * @deprecated use linphone_core_find_friend() instead.
Ghislain MARY's avatar
Ghislain MARY committed
394
 */
Ghislain MARY's avatar
Ghislain MARY committed
395
LINPHONE_PUBLIC LinphoneFriend *linphone_core_get_friend_by_address(const LinphoneCore *lc, const char *addr);
Ghislain MARY's avatar
Ghislain MARY committed
396

Simon Morlat's avatar
Simon Morlat committed
397 398 399 400
/**
 * Search a LinphoneFriend by its address.
 * @param[in] lc #LinphoneCore object.
 * @param[in] addr The address to use to search the friend.
401
 * @return The #LinphoneFriend object corresponding to the given address.
Simon Morlat's avatar
Simon Morlat committed
402 403 404
 */
LINPHONE_PUBLIC LinphoneFriend *linphone_core_find_friend(const LinphoneCore *lc, const LinphoneAddress *addr);

Ghislain MARY's avatar
Ghislain MARY committed
405 406 407 408
/**
 * Search a LinphoneFriend by its reference key.
 * @param[in] lc #LinphoneCore object.
 * @param[in] key The reference key to use to search the friend.
409
 * @return The #LinphoneFriend object corresponding to the given reference key.
Ghislain MARY's avatar
Ghislain MARY committed
410
 */
Ghislain MARY's avatar
Ghislain MARY committed
411
LINPHONE_PUBLIC LinphoneFriend *linphone_core_get_friend_by_ref_key(const LinphoneCore *lc, const char *key);
jehan's avatar
jehan committed
412

413 414 415 416 417 418 419 420 421 422 423 424
/**
 * 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.
 * @param[in] lf LinohoneFriend object
**/
LINPHONE_PUBLIC void linphone_friend_unref(LinphoneFriend *lf);
425 426 427 428 429

/**
 * Returns the LinphoneCore object managing this friend, if any.
 */
LINPHONE_PUBLIC LinphoneCore *linphone_friend_get_core(const LinphoneFriend *fr);
jehan's avatar
jehan committed
430 431 432 433 434 435 436 437 438
/**
 * @}
 */

#ifdef __cplusplus
}
#endif

#endif /* LINPHONEFRIEND_H_ */