friend.h 12 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 LINPHONE_FRIEND_H_
#define LINPHONE_FRIEND_H_
22

23
#include "linphone/types.h"
24

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
 * @{
 */

/**
 * Contructor
 * @return a new empty #LinphoneFriend
37
 * @deprecated use #linphone_core_create_friend instead
38
 * @donotwrap
jehan's avatar
jehan committed
39
 */
jehan's avatar
jehan committed
40
LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneFriend * linphone_friend_new(void);
Ghislain MARY's avatar
Ghislain MARY committed
41

jehan's avatar
jehan committed
42
/**
Ghislain MARY's avatar
Ghislain MARY committed
43
 * Contructor same as linphone_friend_new() + linphone_friend_set_address()
jehan's avatar
jehan committed
44 45
 * @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
46
 * @deprecated use #linphone_core_create_friend_with_address instead
47
 * @donotwrap
jehan's avatar
jehan committed
48
 */
jehan's avatar
jehan committed
49
LINPHONE_PUBLIC	LINPHONE_DEPRECATED LinphoneFriend *linphone_friend_new_with_address(const char *addr);
Ghislain MARY's avatar
Ghislain MARY committed
50 51 52 53 54 55

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

jehan's avatar
jehan committed
57
/**
58 59 60
 * Destroy a LinphoneFriend.
 * @param lf LinphoneFriend object
 * @deprecated Use linphone_friend_unref() instead.
61
 * @donotwrap
jehan's avatar
jehan committed
62
 */
63
LINPHONE_PUBLIC LINPHONE_DEPRECATED void linphone_friend_destroy(LinphoneFriend *lf);
jehan's avatar
jehan committed
64

jehan's avatar
jehan committed
65
/**
66
 * Set #LinphoneAddress for this friend
jehan's avatar
jehan committed
67
 * @param fr #LinphoneFriend object
jehan's avatar
jehan committed
68 69
 * @param address #LinphoneAddress
 */
70
LINPHONE_PUBLIC LinphoneStatus linphone_friend_set_address(LinphoneFriend *fr, const LinphoneAddress* address);
71 72 73 74 75 76

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

78
/**
79 80
 * Get address of this friend.
 * @note the LinphoneAddress object returned is hold by the LinphoneFriend, however calling several time this function may return different objects.
81 82 83
 * @param lf #LinphoneFriend object
 * @return #LinphoneAddress
 */
84
LINPHONE_PUBLIC const LinphoneAddress * linphone_friend_get_address(const LinphoneFriend *lf);
85 86 87 88 89 90 91 92 93 94 95

/**
 * 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
96
 * @return \bctbx_list{LinphoneAddress}
97
 */
98
LINPHONE_PUBLIC const bctbx_list_t* linphone_friend_get_addresses(const LinphoneFriend *lf);
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116

/**
 * 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
117
 * @return \bctbx_list{const char *}
118
 */
119
LINPHONE_PUBLIC bctbx_list_t* linphone_friend_get_phone_numbers(LinphoneFriend *lf);
120 121 122 123 124 125 126

/**
 * 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);
127 128 129

/**
 * Set the display name for this friend
130
 * @param lf #LinphoneFriend object
131
 * @param name
132
 */
133
LINPHONE_PUBLIC LinphoneStatus linphone_friend_set_name(LinphoneFriend *lf, const char *name);
134

jehan's avatar
jehan committed
135
/**
136
 * Get the display name for this friend
jehan's avatar
jehan committed
137
 * @param lf #LinphoneFriend object
138
 * @return The display name of this friend
jehan's avatar
jehan committed
139
 */
140 141
LINPHONE_PUBLIC const char * linphone_friend_get_name(const LinphoneFriend *lf);

jehan's avatar
jehan committed
142 143 144 145
/**
 * get subscription flag value
 * @param lf #LinphoneFriend object
 * @return returns true is subscription is activated for this friend
jehan's avatar
jehan committed
146 147
 *
 */
Ghislain MARY's avatar
Ghislain MARY committed
148
LINPHONE_PUBLIC bool_t linphone_friend_subscribes_enabled(const LinphoneFriend *lf);
jehan's avatar
jehan committed
149 150
#define linphone_friend_get_send_subscribe linphone_friend_subscribes_enabled

jehan's avatar
jehan committed
151 152 153 154 155 156
/**
 * Configure #LinphoneFriend to subscribe to presence information
 * @param fr #LinphoneFriend object
 * @param val if TRUE this friend will receive subscription message
 */

157
LINPHONE_PUBLIC	LinphoneStatus linphone_friend_enable_subscribes(LinphoneFriend *fr, bool_t val);
jehan's avatar
jehan committed
158
#define linphone_friend_send_subscribe linphone_friend_enable_subscribes
Ghislain MARY's avatar
Ghislain MARY committed
159

jehan's avatar
jehan committed
160 161 162 163 164
/**
 * Configure incoming subscription policy for this friend.
 * @param fr #LinphoneFriend object
 * @param pol #LinphoneSubscribePolicy policy to apply.
 */
165
LINPHONE_PUBLIC LinphoneStatus linphone_friend_set_inc_subscribe_policy(LinphoneFriend *fr, LinphoneSubscribePolicy pol);
Ghislain MARY's avatar
Ghislain MARY committed
166

jehan's avatar
jehan committed
167 168 169 170 171 172
/**
 * get current subscription policy for this #LinphoneFriend
 * @param lf #LinphoneFriend object
 * @return #LinphoneSubscribePolicy
 *
 */
Ghislain MARY's avatar
Ghislain MARY committed
173
LINPHONE_PUBLIC LinphoneSubscribePolicy linphone_friend_get_inc_subscribe_policy(const LinphoneFriend *lf);
jehan's avatar
jehan committed
174

jehan's avatar
jehan committed
175 176 177 178 179
/**
 * 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
180
 * 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
181 182 183
 * Once the modifications are done, then the application must call
 * linphone_friend_done() to commit the changes.
**/
184
LINPHONE_PUBLIC	void linphone_friend_edit(LinphoneFriend *fr);
Ghislain MARY's avatar
Ghislain MARY committed
185

jehan's avatar
jehan committed
186 187 188 189
/**
 * Commits modification made to the friend configuration.
 * @param fr #LinphoneFriend object
**/
190
LINPHONE_PUBLIC	void linphone_friend_done(LinphoneFriend *fr);
jehan's avatar
jehan committed
191

jehan's avatar
jehan committed
192
/**
193
 * Get the status of a friend
194
 * @param[in] lf A #LinphoneFriend object
jehan's avatar
jehan committed
195
 * @return #LinphoneOnlineStatus
196
 * @deprecated Use linphone_friend_get_presence_model() instead
197
 * @donotwrap
jehan's avatar
jehan committed
198
 */
199
LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneOnlineStatus linphone_friend_get_status(const LinphoneFriend *lf);
200

201 202 203 204 205 206 207
/**
 * 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);
208

209
/**
210
 * Get the presence model of a friend
211
 * @param[in] lf A #LinphoneFriend object
Ghislain MARY's avatar
Ghislain MARY committed
212
 * @return A #LinphonePresenceModel object, or NULL if the friend do not have presence information (in which case he is considered offline)
213
 */
214 215
LINPHONE_PUBLIC const LinphonePresenceModel * linphone_friend_get_presence_model(const LinphoneFriend *lf);

216 217 218 219 220 221 222
/**
 * Get the consolidated presence of a friend.
 * @param[in] lf LinphoneFriend object
 * @return The consolidated presence of the friend
 */
LINPHONE_PUBLIC LinphoneConsolidatedPresence linphone_friend_get_consolidated_presence(const LinphoneFriend *lf);

223 224 225 226 227 228 229
/**
 * 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);
230

231 232 233 234 235 236 237
/**
 * 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);

238 239 240 241 242 243 244 245
/**
 * 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);

246 247 248 249 250 251 252
/**
 * 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
253 254 255 256 257 258 259 260 261 262
/**
 * 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
263
LINPHONE_PUBLIC BuddyInfo * linphone_friend_get_info(const LinphoneFriend *lf);
Ghislain MARY's avatar
Ghislain MARY committed
264 265 266 267 268 269

/**
 * 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
270
LINPHONE_PUBLIC void linphone_friend_set_ref_key(LinphoneFriend *lf, const char *key);
Ghislain MARY's avatar
Ghislain MARY committed
271 272 273 274

/**
 * Get the reference key of a friend.
 * @param[in] lf #LinphoneFriend object.
275
 * @return The reference key of the friend.
Ghislain MARY's avatar
Ghislain MARY committed
276
**/
Ghislain MARY's avatar
Ghislain MARY committed
277
LINPHONE_PUBLIC const char *linphone_friend_get_ref_key(const LinphoneFriend *lf);
Ghislain MARY's avatar
Ghislain MARY committed
278 279 280 281

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

286 287 288 289 290 291 292 293 294
/**
 * 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.
295
 * @param[in] lf LinphoneFriend object
296 297
**/
LINPHONE_PUBLIC void linphone_friend_unref(LinphoneFriend *lf);
298 299 300

/**
 * Returns the LinphoneCore object managing this friend, if any.
301
 * @param[in] fr LinphoneFriend object
302 303
 */
LINPHONE_PUBLIC LinphoneCore *linphone_friend_get_core(const LinphoneFriend *fr);
304 305

/**
306
 * Returns the vCard object associated to this friend, if any
307
 * @param[in] fr LinphoneFriend object
308
 */
309
LINPHONE_PUBLIC LinphoneVcard* linphone_friend_get_vcard(LinphoneFriend *fr);
310 311

/**
312
 * Binds a vCard object to a friend
313
 * @param[in] fr LinphoneFriend object
314
 * @param[in] vcard The vCard object to bind
315
 */
316
LINPHONE_PUBLIC void linphone_friend_set_vcard(LinphoneFriend *fr, LinphoneVcard *vcard);
317 318

/**
319
 * 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
320 321 322 323 324
 * @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);
325 326 327

/**
 * Contructor same as linphone_friend_new() + linphone_friend_set_address()
328 329
 * @param vcard a vCard object
 * @return a new #LinphoneFriend with \link linphone_friend_get_vcard() vCard initialized \endlink
330
 */
331
LINPHONE_PUBLIC	LinphoneFriend *linphone_friend_new_from_vcard(LinphoneVcard *vcard);
332

333 334 335 336 337
/**
 * Saves a friend either in database if configured, otherwise in linphonerc
 * @param fr the linphone friend to save
 * @param lc the linphone core
 */
338
LINPHONE_PUBLIC void linphone_friend_save(LinphoneFriend *fr, LinphoneCore *lc);
339

jehan's avatar
jehan committed
340 341 342 343 344 345 346 347
/**
 * @}
 */

#ifdef __cplusplus
}
#endif

348
#endif /* LINPHONE_FRIEND_H_ */