friendlist.h 15.2 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
/*
friendlist.h
Copyright (C) 2010-2015 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.
18 19 20 21 22 23 24
*/


#ifndef LINPHONE_FRIENDLIST_H_
#define LINPHONE_FRIENDLIST_H_


25
#include "linphone/types.h"
26 27 28 29 30 31 32 33 34 35 36 37 38


#ifdef __cplusplus
extern "C" {
#endif

/**
 * @addtogroup buddy_list
 * @{
 */

/**
 * Acquire a reference to the friend list.
39 40
 * @param[in] list #LinphoneFriendList object.
 * @return The same #LinphoneFriendList object.
41 42 43 44 45
**/
LINPHONE_PUBLIC LinphoneFriendList * linphone_friend_list_ref(LinphoneFriendList *list);

/**
 * Release reference to the friend list.
46
 * @param[in] list #LinphoneFriendList object.
47 48 49 50 51
**/
LINPHONE_PUBLIC void linphone_friend_list_unref(LinphoneFriendList *list);

/**
 * Retrieve the user pointer associated with the friend list.
52
 * @param[in] list #LinphoneFriendList object.
53 54 55 56 57 58
 * @return The user pointer associated with the friend list.
**/
LINPHONE_PUBLIC void * linphone_friend_list_get_user_data(const LinphoneFriendList *list);

/**
 * Assign a user pointer to the friend list.
59
 * @param[in] list #LinphoneFriendList object.
60 61 62 63 64 65
 * @param[in] ud The user pointer to associate with the friend list.
**/
LINPHONE_PUBLIC void linphone_friend_list_set_user_data(LinphoneFriendList *list, void *ud);

/**
 * Get the display name of the friend list.
66
 * @param[in] list #LinphoneFriendList object.
67 68 69 70 71 72
 * @return The display name of the friend list.
**/
LINPHONE_PUBLIC const char * linphone_friend_list_get_display_name(const LinphoneFriendList *list);

/**
 * Set the display name of the friend list.
73
 * @param[in] list #LinphoneFriendList object.
74 75 76 77 78 79
 * @param[in] display_name The new display name of the friend list.
**/
LINPHONE_PUBLIC void linphone_friend_list_set_display_name(LinphoneFriendList *list, const char *display_name);

/**
 * Get the RLS (Resource List Server) URI associated with the friend list to subscribe to these friends presence.
80
 * @param[in] list #LinphoneFriendList object.
81 82 83 84 85 86
 * @return The RLS URI associated with the friend list.
**/
LINPHONE_PUBLIC const char * linphone_friend_list_get_rls_uri(const LinphoneFriendList *list);

/**
 * Set the RLS (Resource List Server) URI associated with the friend list to subscribe to these friends presence.
87
 * @param[in] list #LinphoneFriendList object.
88 89 90 91
 * @param[in] rls_uri The RLS URI to associate with the friend list.
**/
LINPHONE_PUBLIC void linphone_friend_list_set_rls_uri(LinphoneFriendList *list, const char *rls_uri);

92 93
/**
 * Get the RLS (Resource List Server) URI associated with the friend list to subscribe to these friends presence.
94
 * @param[in] list #LinphoneFriendList object.
95 96 97 98 99 100
 * @return The RLS URI associated with the friend list.
**/
LINPHONE_PUBLIC const LinphoneAddress * linphone_friend_list_get_rls_address(const LinphoneFriendList *list);

/**
 * Set the RLS (Resource List Server) URI associated with the friend list to subscribe to these friends presence.
101
 * @param[in] list #LinphoneFriendList object.
102 103 104 105
 * @param[in] rls_addr The RLS URI to associate with the friend list.
**/
LINPHONE_PUBLIC void linphone_friend_list_set_rls_address(LinphoneFriendList *list, const LinphoneAddress *rls_addr);

106
/**
107
 * Add a friend to a friend list. If or when a remote CardDAV server will be attached to the list, the friend will be sent to the server.
108 109 110
 * @param[in] list #LinphoneFriendList object.
 * @param[in] lf #LinphoneFriend object to add to the friend list.
 * @return #LinphoneFriendListOK if successfully added, #LinphoneFriendListInvalidFriend if the friend is not valid.
111
**/
112 113 114 115
LINPHONE_PUBLIC LinphoneFriendListStatus linphone_friend_list_add_friend(LinphoneFriendList *list, LinphoneFriend *lf);

/**
 * Add a friend to a friend list. The friend will never be sent to a remote CardDAV server.
116 117 118 119
 * Warning! #LinphoneFriends added this way will be removed on the next synchronization, and the callback contact_deleted will be called.
 * @param[in] list #LinphoneFriendList object.
 * @param[in] lf #LinphoneFriend object to add to the friend list.
 * @return #LinphoneFriendListOK if successfully added, #LinphoneFriendListInvalidFriend if the friend is not valid.
120 121
**/
LINPHONE_PUBLIC LinphoneFriendListStatus linphone_friend_list_add_local_friend(LinphoneFriendList *list, LinphoneFriend *lf);
122 123 124

/**
 * Remove a friend from a friend list.
125 126 127
 * @param[in] list #LinphoneFriendList object.
 * @param[in] lf #LinphoneFriend object to remove from the friend list.
 * @return #LinphoneFriendListOK if removed successfully, #LinphoneFriendListNonExistentFriend if the friend is not in the list.
128
**/
129
LINPHONE_PUBLIC LinphoneFriendListStatus linphone_friend_list_remove_friend(LinphoneFriendList *list, LinphoneFriend *lf);
130

131
/**
132 133 134
 * Retrieves the list of #LinphoneFriend from this LinphoneFriendList.
 * @param[in] list #LinphoneFriendList object
 * @return \bctbx_list{LinphoneFriend} a list of #LinphoneFriend
135
 */
136
LINPHONE_PUBLIC const bctbx_list_t * linphone_friend_list_get_friends(const LinphoneFriendList *list);
137

138 139
/**
 * Find a friend in the friend list using a LinphoneAddress.
140 141 142
 * @param[in] list #LinphoneFriendList object.
 * @param[in] address #LinphoneAddress object of the friend we want to search for.
 * @return A #LinphoneFriend if found, NULL otherwise.
143
**/
144 145
LINPHONE_PUBLIC LinphoneFriend * linphone_friend_list_find_friend_by_address(const LinphoneFriendList *list, const LinphoneAddress *address);

146 147
/**
 * Find a friend in the friend list using an URI string.
148
 * @param[in] list #LinphoneFriendList object.
149
 * @param[in] uri A string containing the URI of the friend we want to search for.
150
 * @return A #LinphoneFriend if found, NULL otherwise.
151
**/
152 153
LINPHONE_PUBLIC LinphoneFriend * linphone_friend_list_find_friend_by_uri(const LinphoneFriendList *list, const char *uri);

154
/**
155
 * Find a friend in the friend list using a ref key.
156
 * @param[in] list #LinphoneFriendList object.
157
 * @param[in] ref_key The ref key string of the friend we want to search for.
158
 * @return A #LinphoneFriend if found, NULL otherwise.
159
**/
160 161
LINPHONE_PUBLIC LinphoneFriend * linphone_friend_list_find_friend_by_ref_key(const LinphoneFriendList *list, const char *ref_key);

162 163 164 165 166 167
/**
 * Update presence subscriptions for the entire list. Calling this function is necessary when list subscriptions are enabled,
 * ie when a RLS presence server is used.
 * @param[in] list the friend list
**/
LINPHONE_PUBLIC void linphone_friend_list_update_subscriptions(LinphoneFriendList *list);
168

169 170
/**
 * Notify our presence to all the friends in the friend list that have subscribed to our presence directly (not using a RLS).
171 172
 * @param[in] list #LinphoneFriendList object.
 * @param[in] presence #LinphonePresenceModel object.
173
**/
174 175
LINPHONE_PUBLIC void linphone_friend_list_notify_presence(LinphoneFriendList *list, LinphonePresenceModel *presence);

176 177
/**
 * Get the URI associated with the friend list.
178
 * @param[in] list #LinphoneFriendList object.
179 180 181 182 183 184
 * @return The URI associated with the friend list.
**/
LINPHONE_PUBLIC const char * linphone_friend_list_get_uri(const LinphoneFriendList *list);

/**
 * Set the URI associated with the friend list.
185
 * @param[in] list #LinphoneFriendList object.
186
 * @param[in] uri The URI to associate with the friend list.
187 188 189
**/
LINPHONE_PUBLIC void linphone_friend_list_set_uri(LinphoneFriendList *list, const char *uri);

190 191 192 193 194 195 196 197 198 199 200 201 202 203
/**
 * Get wheter the subscription of the friend list is bodyless or not.
 * @param[in] list #LinphoneFriendList object.
 * @return Wheter the subscription of the friend list is bodyless or not.
**/
LINPHONE_PUBLIC bool_t linphone_friend_list_is_subscription_bodyless(LinphoneFriendList *list);

/**
 * Set wheter the subscription of the friend list is bodyless or not.
 * @param[in] list #LinphoneFriendList object.
 * @param[in] a boolean telling if the subscription of the friend list is bodyless or not.
**/
LINPHONE_PUBLIC void linphone_friend_list_set_subscription_bodyless(LinphoneFriendList *list, bool_t bodyless);

204 205
/**
 * Sets the revision from the last synchronization.
206
 * @param[in] list #LinphoneFriendList object.
207 208
 * @param[in] rev The revision
 */
209
LINPHONE_PUBLIC void linphone_friend_list_update_revision(LinphoneFriendList *list, int rev);
210 211

/**
212 213 214
 * Get the #LinphoneFriendListCbs object associated with a LinphoneFriendList.
 * @param[in] list #LinphoneFriendList object
 * @return The #LinphoneFriendListCbs object associated with the LinphoneFriendList.
215 216 217 218
**/
LINPHONE_PUBLIC LinphoneFriendListCbs * linphone_friend_list_get_callbacks(const LinphoneFriendList *list);

/**
219 220 221
 * Acquire a reference to a #LinphoneFriendListCbs object.
 * @param[in] cbs #LinphoneFriendListCbs object.
 * @return The same #LinphoneFriendListCbs object.
222 223 224 225
**/
LINPHONE_PUBLIC LinphoneFriendListCbs * linphone_friend_list_cbs_ref(LinphoneFriendListCbs *cbs);

/**
226 227
 * Release a reference to a #LinphoneFriendListCbs object.
 * @param[in] cbs #LinphoneFriendListCbs object.
228 229 230 231
**/
LINPHONE_PUBLIC void linphone_friend_list_cbs_unref(LinphoneFriendListCbs *cbs);

/**
232 233 234
 * Retrieve the user pointer associated with a #LinphoneFriendListCbs object.
 * @param[in] cbs #LinphoneFriendListCbs object.
 * @return The user pointer associated with the #LinphoneFriendListCbs object.
235 236 237 238
**/
LINPHONE_PUBLIC void *linphone_friend_list_cbs_get_user_data(const LinphoneFriendListCbs *cbs);

/**
239 240 241
 * Assign a user pointer to a #LinphoneFriendListCbs object.
 * @param[in] cbs #LinphoneFriendListCbs object.
 * @param[in] ud The user pointer to associate with the #LinphoneFriendListCbs object.
242 243 244 245 246
**/
LINPHONE_PUBLIC void linphone_friend_list_cbs_set_user_data(LinphoneFriendListCbs *cbs, void *ud);

/**
 * Get the contact created callback.
247
 * @param[in] cbs #LinphoneFriendListCbs object.
248 249
 * @return The current contact created callback.
**/
250
LINPHONE_PUBLIC LinphoneFriendListCbsContactCreatedCb linphone_friend_list_cbs_get_contact_created(const LinphoneFriendListCbs *cbs);
251 252 253

/**
 * Set the contact created callback.
254
 * @param[in] cbs #LinphoneFriendListCbs object.
255 256
 * @param[in] cb The contact created to be used.
**/
257
LINPHONE_PUBLIC void linphone_friend_list_cbs_set_contact_created(LinphoneFriendListCbs *cbs, LinphoneFriendListCbsContactCreatedCb cb);
258 259 260

/**
 * Get the contact deleted callback.
261
 * @param[in] cbs #LinphoneFriendListCbs object.
262 263
 * @return The current contact deleted callback.
**/
264
LINPHONE_PUBLIC LinphoneFriendListCbsContactDeletedCb linphone_friend_list_cbs_get_contact_deleted(const LinphoneFriendListCbs *cbs);
265 266 267

/**
 * Set the contact deleted callback.
268
 * @param[in] cbs #LinphoneFriendListCbs object.
269 270
 * @param[in] cb The contact deleted to be used.
**/
271
LINPHONE_PUBLIC void linphone_friend_list_cbs_set_contact_deleted(LinphoneFriendListCbs *cbs, LinphoneFriendListCbsContactDeletedCb cb);
272

273 274
/**
 * Get the contact updated callback.
275
 * @param[in] cbs #LinphoneFriendListCbs object.
276 277
 * @return The current contact updated callback.
**/
278
LINPHONE_PUBLIC LinphoneFriendListCbsContactUpdatedCb linphone_friend_list_cbs_get_contact_updated(const LinphoneFriendListCbs *cbs);
279 280 281

/**
 * Set the contact updated callback.
282
 * @param[in] cbs #LinphoneFriendListCbs object.
283 284
 * @param[in] cb The contact updated to be used.
**/
285
LINPHONE_PUBLIC void linphone_friend_list_cbs_set_contact_updated(LinphoneFriendListCbs *cbs, LinphoneFriendListCbsContactUpdatedCb cb);
286

287 288
/**
 * Get the sync status changed callback.
289
 * @param[in] cbs #LinphoneFriendListCbs object.
290 291
 * @return The current sync status changedcallback.
**/
292
LINPHONE_PUBLIC LinphoneFriendListCbsSyncStateChangedCb linphone_friend_list_cbs_get_sync_status_changed(const LinphoneFriendListCbs *cbs);
293 294 295

/**
 * Set the contact updated callback.
296
 * @param[in] cbs #LinphoneFriendListCbs object.
297 298
 * @param[in] cb The sync status changed to be used.
**/
299
LINPHONE_PUBLIC void linphone_friend_list_cbs_set_sync_status_changed(LinphoneFriendListCbs *cbs, LinphoneFriendListCbsSyncStateChangedCb cb);
300

301 302 303 304 305 306 307 308 309 310 311 312 313 314
/**
 * Get the presence received callback.
 * @param[in] cbs #LinphoneFriendListCbs object.
 * @return The current presence received callback.
**/
LINPHONE_PUBLIC LinphoneFriendListCbsPresenceReceivedCb linphone_friend_list_cbs_get_presence_received(const LinphoneFriendListCbs *cbs);

/**
 * Set the presence received callback.
 * @param[in] cbs #LinphoneFriendListCbs object.
 * @param[in] cb The presence received callback to be used.
**/
LINPHONE_PUBLIC void linphone_friend_list_cbs_set_presence_received(LinphoneFriendListCbs *cbs, LinphoneFriendListCbsPresenceReceivedCb cb);

315
/**
316
 * Starts a CardDAV synchronization using value set using linphone_friend_list_set_uri.
317
 * @param[in] list #LinphoneFriendList object.
318 319 320 321
 */
LINPHONE_PUBLIC void linphone_friend_list_synchronize_friends_from_server(LinphoneFriendList *list);

/**
322 323
 * Goes through all the #LinphoneFriend that are dirty and does a CardDAV PUT to update the server.
 * @param[in] list #LinphoneFriendList object.
324
 */
325
LINPHONE_PUBLIC void linphone_friend_list_update_dirty_friends(LinphoneFriendList *list);
326

327
/**
328 329 330
 * Returns the #LinphoneCore object attached to this LinphoneFriendList.
 * @param[in] list #LinphoneFriendList object.
 * @return a #LinphoneCore object
331
 */
332
LINPHONE_PUBLIC LinphoneCore* linphone_friend_list_get_core(const LinphoneFriendList *list);
333

334
/**
335 336
 * Creates and adds #LinphoneFriend objects to #LinphoneFriendList from a file that contains the vCard(s) to parse
 * @param[in] list the #LinphoneFriendList object
337 338 339
 * @param[in] vcard_file the path to a file that contains the vCard(s) to parse
 * @return the amount of linphone friends created
 */
340
LINPHONE_PUBLIC LinphoneStatus linphone_friend_list_import_friends_from_vcard4_file(LinphoneFriendList *list, const char *vcard_file);
341 342

/**
343 344
 * Creates and adds #LinphoneFriend objects to #LinphoneFriendList from a buffer that contains the vCard(s) to parse
 * @param[in] list the #LinphoneFriendList object
345 346 347
 * @param[in] vcard_buffer the buffer that contains the vCard(s) to parse
 * @return the amount of linphone friends created
 */
348
LINPHONE_PUBLIC LinphoneStatus linphone_friend_list_import_friends_from_vcard4_buffer(LinphoneFriendList *list, const char *vcard_buffer);
349 350

/**
351 352
 * Creates and export #LinphoneFriend objects from #LinphoneFriendList to a file using vCard 4 format
 * @param[in] list the #LinphoneFriendList object
353 354 355 356
 * @param[in] vcard_file the path to a file that will contain the vCards
 */
LINPHONE_PUBLIC void linphone_friend_list_export_friends_as_vcard4_file(LinphoneFriendList *list, const char *vcard_file);

357 358
/**
 * Enable subscription to NOTIFYes of all friends list
359
 * @param[in] list the #LinphoneFriendList object
360 361 362 363
 * @param[in] enabled should subscription be enabled or not
 */
LINPHONE_PUBLIC void linphone_friend_list_enable_subscriptions(LinphoneFriendList *list, bool_t enabled);

364 365
/**
 * Gets whether subscription to NOTIFYes of all friends list are enabled or not
366
 * @param[in] list the #LinphoneFriendList object
367 368 369 370
 * @return Whether subscriptions are enabled or not
 */
LINPHONE_PUBLIC bool_t linphone_friend_list_subscriptions_enabled(LinphoneFriendList *list);

371 372 373 374 375 376 377 378 379
/**
 * @}
 */

#ifdef __cplusplus
}
#endif

#endif /* LINPHONE_FRIENDLIST_H_ */