linphonepresence.h 39.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
/*
linphonepresence.h
Copyright (C) 2010-2013  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 LINPHONEPRESENCE_H_
#define LINPHONEPRESENCE_H_

23

24 25 26 27 28
#ifdef __cplusplus
extern "C" {
#endif


29 30 31 32 33 34
/**
 * @addtogroup buddy_list
 * @{
 */


35 36
/** Basic status as defined in section 4.1.4 of RFC 3863 */
typedef enum LinphonePresenceBasicStatus {
37
	/** This value means that the associated contact element, if any, is ready to accept communication. */
38
	LinphonePresenceBasicStatusOpen,
39 40

	/** This value means that the associated contact element, if any, is unable to accept communication. */
41 42 43 44
	LinphonePresenceBasicStatusClosed
} LinphonePresenceBasicStatus;

/** Activities as defined in section 3.2 of RFC 4480 */
Ghislain MARY's avatar
Ghislain MARY committed
45
typedef enum LinphonePresenceActivityType {
46
	/** This value is not defined in the RFC, it corresponds to no activity with a basic status of "closed". */
47
	LinphonePresenceActivityOffline,
48 49

	/** This value is not defined in the RFC, it corresponds to no activity with a basic status of "open". */
50
	LinphonePresenceActivityOnline,
51 52 53 54

	/** The person has a calendar appointment, without specifying exactly of what type. This activity is
	 *  indicated if more detailed information is not available or the person chooses not to reveal more
	 * information. */
55
	LinphonePresenceActivityAppointment,
56 57

	/** The person is physically away from all interactive communication devices. */
58
	LinphonePresenceActivityAway,
59 60

	/** The person is eating the first meal of the day, usually eaten in the morning. */
61
	LinphonePresenceActivityBreakfast,
62 63

	/** The person is busy, without further details. */
64
	LinphonePresenceActivityBusy,
65 66

	/** The person is having his or her main meal of the day, eaten in the evening or at midday. */
67
	LinphonePresenceActivityDinner,
68 69

	/**  This is a scheduled national or local holiday. */
70
	LinphonePresenceActivityHoliday,
71 72

	/** The person is riding in a vehicle, such as a car, but not steering. */
73
	LinphonePresenceActivityInTransit,
74 75

	/** The person is looking for (paid) work. */
76
	LinphonePresenceActivityLookingForWork,
77 78

	/** The person is eating his or her midday meal. */
79
	LinphonePresenceActivityLunch,
80 81 82

	/** The person is scheduled for a meal, without specifying whether it is breakfast, lunch, or dinner,
	 *  or some other meal. */
83
	LinphonePresenceActivityMeal,
84 85 86

	/** The person is in an assembly or gathering of people, as for a business, social, or religious purpose.
	 *  A meeting is a sub-class of an appointment. */
87
	LinphonePresenceActivityMeeting,
88 89

	/** The person is talking on the telephone. */
90
	LinphonePresenceActivityOnThePhone,
91 92 93

	/** The person is engaged in an activity with no defined representation. A string describing the activity
	 *  in plain text SHOULD be provided. */
94
	LinphonePresenceActivityOther,
95 96 97 98 99

	/** A performance is a sub-class of an appointment and includes musical, theatrical, and cinematic
	 *  performances as well as lectures. It is distinguished from a meeting by the fact that the person
	 *  may either be lecturing or be in the audience, with a potentially large number of other people,
	 *  making interruptions particularly noticeable. */
100
	LinphonePresenceActivityPerformance,
101 102 103

	/** The person will not return for the foreseeable future, e.g., because it is no longer working for
	 *  the company. */
104
	LinphonePresenceActivityPermanentAbsence,
105 106

	/** The person is occupying himself or herself in amusement, sport, or other recreation. */
107
	LinphonePresenceActivityPlaying,
108 109

	/** The person is giving a presentation, lecture, or participating in a formal round-table discussion. */
110
	LinphonePresenceActivityPresentation,
111 112

	/** The person is visiting stores in search of goods or services. */
113
	LinphonePresenceActivityShopping,
114 115

	/** The person is sleeping.*/
116
	LinphonePresenceActivitySleeping,
117 118

	/** The person is observing an event, such as a sports event. */
119
	LinphonePresenceActivitySpectator,
120 121

	/** The person is controlling a vehicle, watercraft, or plane. */
122
	LinphonePresenceActivitySteering,
123 124

	/** The person is on a business or personal trip, but not necessarily in-transit. */
125
	LinphonePresenceActivityTravel,
126 127

	/** The person is watching television. */
128
	LinphonePresenceActivityTV,
129 130

	/** The activity of the person is unknown. */
131
	LinphonePresenceActivityUnknown,
132 133

	/** A period of time devoted to pleasure, rest, or relaxation. */
134
	LinphonePresenceActivityVacation,
135 136

	/** The person is engaged in, typically paid, labor, as part of a profession or job. */
137
	LinphonePresenceActivityWorking,
138 139

	/** The person is participating in religious rites. */
140
	LinphonePresenceActivityWorship
141
} LinphonePresenceActivityType;
142

143 144 145
/**
 * Structure holding the information about the presence of a person.
 */
146
struct _LinphonePresenceModel;
147 148 149 150

/**
 * Presence model type holding information about the presence of a person.
 */
151 152
typedef struct _LinphonePresenceModel LinphonePresenceModel;

153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
/**
 * Structure holding the information about a presence service.
 */
struct _LinphonePresenceService;

/**
 * Structure holding the information about a presence person.
 */
struct _LinphonePresencePerson;

/**
 * Presence person holding information about a presence person.
 */
typedef struct _LinphonePresencePerson LinphonePresencePerson;

/**
 * Presence service type holding information about a presence service.
 */
typedef struct _LinphonePresenceService LinphonePresenceService;

173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
/**
 * Structure holding the information about a presence activity.
 */
struct _LinphonePresenceActivity;

/**
 * Presence activity type holding information about a presence activity.
 */
typedef struct _LinphonePresenceActivity LinphonePresenceActivity;

/**
 * Structure holding the information about a presence note.
 */
struct _LinphonePresenceNote;

/**
 * Presence note type holding information about a presence note.
 */
typedef struct _LinphonePresenceNote LinphonePresenceNote;

193

194

195 196 197
/*****************************************************************************
 * HELPER FUNCTIONS TO EASE ACCESS IN MOST SIMPLER CASES                     *
 ****************************************************************************/
198 199

/**
Simon Morlat's avatar
Simon Morlat committed
200
 * Creates a presence model specifying an activity.
201 202 203 204 205 206 207 208
 * @param[in] activity The activity to set for the created presence model.
 * @param[in] description An additional description of the activity (mainly useful for the 'other' activity). Set it to NULL to not add a description.
 * @returns The created presence model, or NULL if an error occured.
 * @see linphone_presence_model_new
 * @see linphone_presence_model_new_with_activity_and_note
 *
 * The created presence model has the activity specified in the parameters.
 */
209
LINPHONE_PUBLIC LinphonePresenceModel * linphone_presence_model_new_with_activity(LinphonePresenceActivityType activity, const char *description);
210 211

/**
Simon Morlat's avatar
Simon Morlat committed
212
 * Creates a presence model specifying an activity and adding a note.
213 214 215 216 217 218 219 220 221 222
 * @param[in] activity The activity to set for the created presence model.
 * @param[in] description An additional description of the activity (mainly useful for the 'other' activity). Set it to NULL to not add a description.
 * @param[in] note An additional note giving additional information about the contact presence.
 * @param[in] lang The language the note is written in. It can be set to NULL in order to not specify the language of the note.
 * @returns The created presence model, or NULL if an error occured.
 * @see linphone_presence_model_new_with_activity
 * @see linphone_presence_model_new_with_activity_and_note
 *
 * The created presence model has the activity and the note specified in the parameters.
 */
223
LINPHONE_PUBLIC LinphonePresenceModel * linphone_presence_model_new_with_activity_and_note(LinphonePresenceActivityType activity, const char *description, const char *note, const char *lang);
224 225

/**
Simon Morlat's avatar
Simon Morlat committed
226
 * Gets the basic status of a presence model.
227 228 229
 * @param[in] model The #LinphonePresenceModel object to get the basic status from.
 * @return The #LinphonePresenceBasicStatus of the #LinphonePresenceModel object given as parameter.
 */
230
LINPHONE_PUBLIC LinphonePresenceBasicStatus linphone_presence_model_get_basic_status(const LinphonePresenceModel *model);
231

232
/**
Simon Morlat's avatar
Simon Morlat committed
233
 *  Sets the basic status of a presence model.
234 235 236 237 238 239
 * @param[in] model The #LinphonePresenceModel object for which to set the basic status.
 * @param[in] basic_status The #LinphonePresenceBasicStatus to set for the #LinphonePresenceModel object.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_model_set_basic_status(LinphonePresenceModel *model, LinphonePresenceBasicStatus basic_status);

240
/**
Simon Morlat's avatar
Simon Morlat committed
241
 *  Gets the timestamp of a presence model.
242 243 244 245 246
 * @param[in] model The #LinphonePresenceModel object to get the timestamp from.
 * @return The timestamp of the #LinphonePresenceModel object or -1 on error.
 */
LINPHONE_PUBLIC time_t linphone_presence_model_get_timestamp(const LinphonePresenceModel *model);

247
/**
Simon Morlat's avatar
Simon Morlat committed
248
 * Gets the contact of a presence model.
249 250 251 252 253 254 255 256
 * @param[in] model The #LinphonePresenceModel object to get the contact from.
 * @return A pointer to a dynamically allocated string containing the contact, or NULL if no contact is found.
 *
 * The returned string is to be freed by calling ms_free().
 */
LINPHONE_PUBLIC char * linphone_presence_model_get_contact(const LinphonePresenceModel *model);

/**
Simon Morlat's avatar
Simon Morlat committed
257
 * Sets the contact of a presence model.
258 259
 * @param[in] model The #LinphonePresenceModel object for which to set the contact.
 * @param[in] contact The contact string to set.
260
 * @return 0 if successful, a value < 0 in case of error.
261
 */
262
LINPHONE_PUBLIC int linphone_presence_model_set_contact(LinphonePresenceModel *model, const char *contact);
263 264

/**
Simon Morlat's avatar
Simon Morlat committed
265
 * Gets the first activity of a presence model (there is usually only one).
266
 * @param[in] model The #LinphonePresenceModel object to get the activity from.
267
 * @return A #LinphonePresenceActivity object if successful, NULL otherwise.
268
 */
269
LINPHONE_PUBLIC LinphonePresenceActivity * linphone_presence_model_get_activity(const LinphonePresenceModel *model);
270 271

/**
Simon Morlat's avatar
Simon Morlat committed
272
 * Sets the activity of a presence model (limits to only one activity).
273
 * @param[in] model The #LinphonePresenceModel object for which to set the activity.
274
 * @param[in] activity The #LinphonePresenceActivityType to set for the model.
275 276
 * @param[in] description An additional description of the activity to set for the model. Can be NULL if no additional description is to be added.
 * @return 0 if successful, a value < 0 in case of error.
277 278 279 280
 *
 * WARNING: This function will modify the basic status of the model according to the activity being set.
 * If you don't want the basic status to be modified automatically, you can use the combination of linphone_presence_model_set_basic_status(),
 * linphone_presence_model_clear_activities() and linphone_presence_model_add_activity().
281
 */
282
LINPHONE_PUBLIC int linphone_presence_model_set_activity(LinphonePresenceModel *model, LinphonePresenceActivityType activity, const char *description);
283

284
/**
Simon Morlat's avatar
Simon Morlat committed
285
 * Gets the number of activities included in the presence model.
286 287 288 289 290 291
 * @param[in] model The #LinphonePresenceModel object to get the number of activities from.
 * @return The number of activities included in the #LinphonePresenceModel object.
 */
LINPHONE_PUBLIC unsigned int linphone_presence_model_nb_activities(const LinphonePresenceModel *model);

/**
Simon Morlat's avatar
Simon Morlat committed
292
 * Gets the nth activity of a presence model.
293 294 295 296 297 298 299
 * @param[in] model The #LinphonePresenceModel object to get the activity from.
 * @param[in] idx The index of the activity to get (the first activity having the index 0).
 * @return A pointer to a #LinphonePresenceActivity object if successful, NULL otherwise.
 */
LINPHONE_PUBLIC LinphonePresenceActivity * linphone_presence_model_get_nth_activity(const LinphonePresenceModel *model, unsigned int idx);

/**
Simon Morlat's avatar
Simon Morlat committed
300
 * Adds an activity to a presence model.
301 302 303 304 305 306 307
 * @param[in] model The #LinphonePresenceModel object for which to add an activity.
 * @param[in] activity The #LinphonePresenceActivity object to add to the model.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_model_add_activity(LinphonePresenceModel *model, LinphonePresenceActivity *activity);

/**
Simon Morlat's avatar
Simon Morlat committed
308
 * Clears the activities of a presence model.
309 310 311 312 313
 * @param[in] model The #LinphonePresenceModel object for which to clear the activities.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_model_clear_activities(LinphonePresenceModel *model);

314
/**
Simon Morlat's avatar
Simon Morlat committed
315
 * Gets the first note of a presence model (there is usually only one).
316
 * @param[in] model The #LinphonePresenceModel object to get the note from.
Ghislain MARY's avatar
Ghislain MARY committed
317
 * @param[in] lang The language of the note to get. Can be NULL to get a note that has no language specified or to get the first note whatever language it is written into.
318
 * @return A pointer to a #LinphonePresenceNote object if successful, NULL otherwise.
319
 */
320
LINPHONE_PUBLIC LinphonePresenceNote * linphone_presence_model_get_note(const LinphonePresenceModel *model, const char *lang);
321 322

/**
Simon Morlat's avatar
Simon Morlat committed
323
 * Adds a note to a presence model.
324 325 326 327 328 329 330
 * @param[in] model The #LinphonePresenceModel object to add a note to.
 * @param[in] note_content The note to be added to the presence model.
 * @param[in] lang The language of the note to be added. Can be NULL if no language is to be specified for the note.
 * @return 0 if successful, a value < 0 in case of error.
 *
 * Only one note for each language can be set, so e.g. setting a note for the 'fr' language if there is only one will replace the existing one.
 */
331
LINPHONE_PUBLIC int linphone_presence_model_add_note(LinphonePresenceModel *model, const char *note_content, const char *lang);
332 333

/**
Simon Morlat's avatar
Simon Morlat committed
334
 * Clears all the notes of a presence model.
335 336 337
 * @param[in] model The #LinphonePresenceModel for which to clear notes.
 * @return 0 if successful, a value < 0 in case of error.
 */
338
LINPHONE_PUBLIC int linphone_presence_model_clear_notes(LinphonePresenceModel *model);
339

340 341 342 343 344

/*****************************************************************************
 * PRESENCE MODEL FUNCTIONS TO GET ACCESS TO ALL FUNCTIONALITIES             *
 ****************************************************************************/

Ghislain MARY's avatar
Ghislain MARY committed
345
/**
Simon Morlat's avatar
Simon Morlat committed
346
 * Creates a default presence model.
347 348 349 350 351
 * @returns The created presence model, NULL on error.
 * @see linphone_presence_model_new_with_activity
 * @see linphone_presence_model_new_with_activity_and_note
 *
 * The created presence model is considered 'offline'.
Ghislain MARY's avatar
Ghislain MARY committed
352
 */
353
LINPHONE_PUBLIC LinphonePresenceModel * linphone_presence_model_new(void);
Ghislain MARY's avatar
Ghislain MARY committed
354 355

/**
Simon Morlat's avatar
Simon Morlat committed
356
 * Gets the number of services included in the presence model.
357 358
 * @param[in] model The #LinphonePresenceModel object to get the number of services from.
 * @return The number of services included in the #LinphonePresenceModel object.
Ghislain MARY's avatar
Ghislain MARY committed
359
 */
360
LINPHONE_PUBLIC unsigned int linphone_presence_model_nb_services(const LinphonePresenceModel *model);
Ghislain MARY's avatar
Ghislain MARY committed
361 362

/**
Simon Morlat's avatar
Simon Morlat committed
363
 * Gets the nth service of a presence model.
364 365 366
 * @param[in] model The #LinphonePresenceModel object to get the service from.
 * @param[in] idx The index of the service to get (the first service having the index 0).
 * @return A pointer to a #LinphonePresenceService object if successful, NULL otherwise.
Ghislain MARY's avatar
Ghislain MARY committed
367
 */
368
LINPHONE_PUBLIC LinphonePresenceService * linphone_presence_model_get_nth_service(const LinphonePresenceModel *model, unsigned int idx);
Ghislain MARY's avatar
Ghislain MARY committed
369 370

/**
Simon Morlat's avatar
Simon Morlat committed
371
 * Adds a service to a presence model.
372 373 374
 * @param[in] model The #LinphonePresenceModel object for which to add a service.
 * @param[in] service The #LinphonePresenceService object to add to the model.
 * @return 0 if successful, a value < 0 in case of error.
Ghislain MARY's avatar
Ghislain MARY committed
375
 */
376 377 378
LINPHONE_PUBLIC int linphone_presence_model_add_service(LinphonePresenceModel *model, LinphonePresenceService *service);

/**
Simon Morlat's avatar
Simon Morlat committed
379
 * Clears the services of a presence model.
380 381 382 383 384
 * @param[in] model The #LinphonePresenceModel object for which to clear the services.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_model_clear_services(LinphonePresenceModel *model);

385
/**
Simon Morlat's avatar
Simon Morlat committed
386
 * Gets the number of persons included in the presence model.
387 388 389 390 391 392
 * @param[in] model The #LinphonePresenceModel object to get the number of persons from.
 * @return The number of persons included in the #LinphonePresenceModel object.
 */
LINPHONE_PUBLIC unsigned int linphone_presence_model_nb_persons(const LinphonePresenceModel *model);

/**
Simon Morlat's avatar
Simon Morlat committed
393
 * Gets the nth person of a presence model.
394 395 396 397 398 399 400
 * @param[in] model The #LinphonePresenceModel object to get the person from.
 * @param[in] idx The index of the person to get (the first person having the index 0).
 * @return A pointer to a #LinphonePresencePerson object if successful, NULL otherwise.
 */
LINPHONE_PUBLIC LinphonePresencePerson * linphone_presence_model_get_nth_person(const LinphonePresenceModel *model, unsigned int idx);

/**
Simon Morlat's avatar
Simon Morlat committed
401
 * Adds a person to a presence model.
402 403 404 405 406 407 408
 * @param[in] model The #LinphonePresenceModel object for which to add a person.
 * @param[in] person The #LinphonePresencePerson object to add to the model.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_model_add_person(LinphonePresenceModel *model, LinphonePresencePerson *person);

/**
Simon Morlat's avatar
Simon Morlat committed
409
 * Clears the persons of a presence model.
410 411 412 413 414
 * @param[in] model The #LinphonePresenceModel object for which to clear the persons.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_model_clear_persons(LinphonePresenceModel *model);

415 416 417 418 419 420

/*****************************************************************************
 * PRESENCE SERVICE FUNCTIONS TO GET ACCESS TO ALL FUNCTIONALITIES           *
 ****************************************************************************/

/**
Simon Morlat's avatar
Simon Morlat committed
421
 * Creates a presence service.
422
 * @param[in] id The id of the presence service to be created. Can be NULL to generate it automatically.
423 424
 * @param[in] basic_status The #LinphonePresenceBasicStatus to set for the #LinphonePresenceService object.
 * @param[in] contact The contact string to set.
425 426 427 428
 * @returns The created presence service, NULL on error.
 *
 * The created presence service has the basic status 'closed'.
 */
429
LINPHONE_PUBLIC LinphonePresenceService * linphone_presence_service_new(const char *id, LinphonePresenceBasicStatus, const char *contact);
430

431
/**
Simon Morlat's avatar
Simon Morlat committed
432
 * Gets the id of a presence service.
433 434 435 436 437 438 439 440
 * @param[in] service The #LinphonePresenceService object to get the id from.
 * @return A pointer to a dynamically allocated string containing the id, or NULL in case of error.
 *
 * The returned string is to be freed by calling ms_free().
 */
LINPHONE_PUBLIC char * linphone_presence_service_get_id(const LinphonePresenceService *service);

/**
Simon Morlat's avatar
Simon Morlat committed
441
 * Sets the id of a presence service.
442 443 444 445 446 447
 * @param[in] service The #LinphonePresenceService object for which to set the id.
 * @param[in] id The id string to set. Can be NULL to generate it automatically.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_service_set_id(LinphonePresenceService *service, const char *id);

448
/**
Simon Morlat's avatar
Simon Morlat committed
449
 * Gets the basic status of a presence service.
450 451 452 453 454 455
 * @param[in] service The #LinphonePresenceService object to get the basic status from.
 * @return The #LinphonePresenceBasicStatus of the #LinphonePresenceService object given as parameter.
 */
LINPHONE_PUBLIC LinphonePresenceBasicStatus linphone_presence_service_get_basic_status(const LinphonePresenceService *service);

/**
Simon Morlat's avatar
Simon Morlat committed
456
 * Sets the basic status of a presence service.
457 458 459 460 461 462 463
 * @param[in] service The #LinphonePresenceService object for which to set the basic status.
 * @param[in] basic_status The #LinphonePresenceBasicStatus to set for the #LinphonePresenceService object.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_service_set_basic_status(LinphonePresenceService *service, LinphonePresenceBasicStatus basic_status);

/**
Simon Morlat's avatar
Simon Morlat committed
464
 * Gets the contact of a presence service.
465 466 467 468 469 470 471 472
 * @param[in] service The #LinphonePresenceService object to get the contact from.
 * @return A pointer to a dynamically allocated string containing the contact, or NULL if no contact is found.
 *
 * The returned string is to be freed by calling ms_free().
 */
LINPHONE_PUBLIC char * linphone_presence_service_get_contact(const LinphonePresenceService *service);

/**
Simon Morlat's avatar
Simon Morlat committed
473
 * Sets the contact of a presence service.
474
 * @param[in] service The #LinphonePresenceService object for which to set the contact.
475 476 477 478 479
 * @param[in] contact The contact string to set.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_service_set_contact(LinphonePresenceService *service, const char *contact);

480
/**
Simon Morlat's avatar
Simon Morlat committed
481
 * Gets the number of notes included in the presence service.
482 483 484 485 486 487
 * @param[in] service The #LinphonePresenceService object to get the number of notes from.
 * @return The number of notes included in the #LinphonePresenceService object.
 */
LINPHONE_PUBLIC unsigned int linphone_presence_service_nb_notes(const LinphonePresenceService *service);

/**
Simon Morlat's avatar
Simon Morlat committed
488
 * Gets the nth note of a presence service.
489 490 491 492 493 494 495
 * @param[in] service The #LinphonePresenceService object to get the note from.
 * @param[in] idx The index of the note to get (the first note having the index 0).
 * @return A pointer to a #LinphonePresenceNote object if successful, NULL otherwise.
 */
LINPHONE_PUBLIC LinphonePresenceNote * linphone_presence_service_get_nth_note(const LinphonePresenceService *service, unsigned int idx);

/**
Simon Morlat's avatar
Simon Morlat committed
496
 * Adds a note to a presence service.
497 498 499 500 501 502 503
 * @param[in] service The #LinphonePresenceService object for which to add a note.
 * @param[in] note The #LinphonePresenceNote object to add to the service.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_service_add_note(LinphonePresenceService *service, LinphonePresenceNote *note);

/**
Simon Morlat's avatar
Simon Morlat committed
504
 * Clears the notes of a presence service.
505 506 507 508 509
 * @param[in] service The #LinphonePresenceService object for which to clear the notes.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_service_clear_notes(LinphonePresenceService *service);

510

511 512 513 514 515
/*****************************************************************************
 * PRESENCE PERSON FUNCTIONS TO GET ACCESS TO ALL FUNCTIONALITIES            *
 ****************************************************************************/

/**
Simon Morlat's avatar
Simon Morlat committed
516
 * Creates a presence person.
517 518 519 520 521 522
 * @param[in] id The id of the presence person to be created. Can be NULL to generate it automatically.
 * @returns The created presence person, NULL on error.
 */
LINPHONE_PUBLIC LinphonePresencePerson * linphone_presence_person_new(const char *id);

/**
Simon Morlat's avatar
Simon Morlat committed
523
 * Gets the id of a presence person.
524 525 526 527 528 529 530 531
 * @param[in] person The #LinphonePresencePerson object to get the id from.
 * @return A pointer to a dynamically allocated string containing the id, or NULL in case of error.
 *
 * The returned string is to be freed by calling ms_free().
 */
LINPHONE_PUBLIC char * linphone_presence_person_get_id(const LinphonePresencePerson *person);

/**
Simon Morlat's avatar
Simon Morlat committed
532
 * Sets the id of a presence person.
533 534 535 536 537 538 539
 * @param[in] person The #LinphonePresencePerson object for which to set the id.
 * @param[in] id The id string to set. Can be NULL to generate it automatically.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_person_set_id(LinphonePresencePerson *person, const char *id);

/**
Simon Morlat's avatar
Simon Morlat committed
540
 * Gets the number of activities included in the presence person.
541 542 543 544 545 546
 * @param[in] person The #LinphonePresencePerson object to get the number of activities from.
 * @return The number of activities included in the #LinphonePresencePerson object.
 */
LINPHONE_PUBLIC unsigned int linphone_presence_person_nb_activities(const LinphonePresencePerson *person);

/**
Simon Morlat's avatar
Simon Morlat committed
547
 * Gets the nth activity of a presence person.
548 549 550 551 552 553 554
 * @param[in] person The #LinphonePresencePerson object to get the activity from.
 * @param[in] idx The index of the activity to get (the first activity having the index 0).
 * @return A pointer to a #LinphonePresenceActivity object if successful, NULL otherwise.
 */
LINPHONE_PUBLIC LinphonePresenceActivity * linphone_presence_person_get_nth_activity(const LinphonePresencePerson *person, unsigned int idx);

/**
Simon Morlat's avatar
Simon Morlat committed
555
 * Adds an activity to a presence person.
556 557 558 559 560 561 562
 * @param[in] person The #LinphonePresencePerson object for which to add an activity.
 * @param[in] activity The #LinphonePresenceActivity object to add to the person.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_person_add_activity(LinphonePresencePerson *person, LinphonePresenceActivity *activity);

/**
Simon Morlat's avatar
Simon Morlat committed
563
 * Clears the activities of a presence person.
564 565 566 567 568
 * @param[in] person The #LinphonePresencePerson object for which to clear the activities.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_person_clear_activities(LinphonePresencePerson *person);

569
/**
Simon Morlat's avatar
Simon Morlat committed
570
 * Gets the number of notes included in the presence person.
571 572 573 574 575 576
 * @param[in] person The #LinphonePresencePerson object to get the number of notes from.
 * @return The number of notes included in the #LinphonePresencePerson object.
 */
LINPHONE_PUBLIC unsigned int linphone_presence_person_nb_notes(const LinphonePresencePerson *person);

/**
Simon Morlat's avatar
Simon Morlat committed
577
 * Gets the nth note of a presence person.
578 579 580 581 582 583 584
 * @param[in] person The #LinphonePresencePerson object to get the note from.
 * @param[in] idx The index of the note to get (the first note having the index 0).
 * @return A pointer to a #LinphonePresenceNote object if successful, NULL otherwise.
 */
LINPHONE_PUBLIC LinphonePresenceNote * linphone_presence_person_get_nth_note(const LinphonePresencePerson *person, unsigned int idx);

/**
Simon Morlat's avatar
Simon Morlat committed
585
 * Adds a note to a presence person.
586 587 588 589 590 591 592
 * @param[in] person The #LinphonePresencePerson object for which to add a note.
 * @param[in] note The #LinphonePresenceNote object to add to the person.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_person_add_note(LinphonePresencePerson *person, LinphonePresenceNote *note);

/**
Simon Morlat's avatar
Simon Morlat committed
593
 * Clears the notes of a presence person.
594 595 596 597 598 599
 * @param[in] person The #LinphonePresencePerson object for which to clear the notes.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_person_clear_notes(LinphonePresencePerson *person);

/**
Simon Morlat's avatar
Simon Morlat committed
600
 * Gets the number of activities notes included in the presence person.
601 602 603 604 605 606
 * @param[in] person The #LinphonePresencePerson object to get the number of activities notes from.
 * @return The number of activities notes included in the #LinphonePresencePerson object.
 */
LINPHONE_PUBLIC unsigned int linphone_presence_person_nb_activities_notes(const LinphonePresencePerson *person);

/**
Simon Morlat's avatar
Simon Morlat committed
607
 * Gets the nth activities note of a presence person.
608 609 610 611 612 613 614
 * @param[in] person The #LinphonePresencePerson object to get the activities note from.
 * @param[in] idx The index of the activities note to get (the first note having the index 0).
 * @return A pointer to a #LinphonePresenceNote object if successful, NULL otherwise.
 */
LINPHONE_PUBLIC LinphonePresenceNote * linphone_presence_person_get_nth_activities_note(const LinphonePresencePerson *person, unsigned int idx);

/**
Simon Morlat's avatar
Simon Morlat committed
615
 * Adds an activities note to a presence person.
616 617 618 619 620 621 622
 * @param[in] person The #LinphonePresencePerson object for which to add an activities note.
 * @param[in] note The #LinphonePresenceNote object to add to the person.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_person_add_activities_note(LinphonePresencePerson *person, LinphonePresenceNote *note);

/**
Simon Morlat's avatar
Simon Morlat committed
623
 * Clears the activities notes of a presence person.
624 625 626
 * @param[in] person The #LinphonePresencePerson object for which to clear the activities notes.
 * @return 0 if successful, a value < 0 in case of error.
 */
Ghislain MARY's avatar
Ghislain MARY committed
627
LINPHONE_PUBLIC int linphone_presence_person_clear_activities_notes(LinphonePresencePerson *person);
628 629


630 631 632
/*****************************************************************************
 * PRESENCE ACTIVITY FUNCTIONS TO GET ACCESS TO ALL FUNCTIONALITIES          *
 ****************************************************************************/
Ghislain MARY's avatar
Ghislain MARY committed
633

634
/**
Simon Morlat's avatar
Simon Morlat committed
635
 * Creates a presence activity.
636 637 638 639 640 641
 * @param[in] acttype The #LinphonePresenceActivityType to set for the activity.
 * @param[in] description An additional description of the activity to set for the activity. Can be NULL if no additional description is to be added.
 * @returns The created presence activity, NULL on error.
 */
LINPHONE_PUBLIC LinphonePresenceActivity * linphone_presence_activity_new(LinphonePresenceActivityType acttype, const char *description);

642
/**
Simon Morlat's avatar
Simon Morlat committed
643
 * Gets the string representation of a presence activity.
644 645 646 647 648 649 650 651
 * @param[in] activity A pointer to the #LinphonePresenceActivity object for which to get a string representation.
 * @return A pointer a dynamically allocated string representing the given activity.
 *
 * The returned string is to be freed by calling ms_free().
 */
LINPHONE_PUBLIC char * linphone_presence_activity_to_string(const LinphonePresenceActivity * activity);

/**
Simon Morlat's avatar
Simon Morlat committed
652
 * Gets the activity type of a presence activity.
653 654 655 656 657
 * @param[in] activity A pointer to the #LinphonePresenceActivity for which to get the type.
 * @return The #LinphonePresenceActivityType of the activity.
 */
LINPHONE_PUBLIC LinphonePresenceActivityType linphone_presence_activity_get_type(const LinphonePresenceActivity *activity);

658
/**
Simon Morlat's avatar
Simon Morlat committed
659
 * Sets the type of activity of a presence activity.
660 661 662 663 664 665
 * @param[in] activity The #LinphonePresenceActivity for which to set for the activity type.
 * @param[in] acttype The activity type to set for the activity.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_activity_set_type(LinphonePresenceActivity *activity, LinphonePresenceActivityType acttype);

666
/**
Simon Morlat's avatar
Simon Morlat committed
667
 * Gets the description of a presence activity.
668 669 670 671 672
 * @param[in] activity A pointer to the #LinphonePresenceActivity for which to get the description.
 * @return A pointer to the description string of the presence activity, or NULL if no description is specified.
 */
LINPHONE_PUBLIC const char * linphone_presence_activity_get_description(const LinphonePresenceActivity *activity);

673
/**
Simon Morlat's avatar
Simon Morlat committed
674
 * Sets the description of a presence activity.
675 676 677 678 679 680
 * @param[in] activity The #LinphonePresenceActivity object for which to set the description.
 * @param[in] description An additional description of the activity. Can be NULL if no additional description is to be added.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_activity_set_description(LinphonePresenceActivity *activity, const char *description);

681 682 683 684 685

/*****************************************************************************
 * PRESENCE NOTE FUNCTIONS TO GET ACCESS TO ALL FUNCTIONALITIES              *
 ****************************************************************************/

Ghislain MARY's avatar
Ghislain MARY committed
686
/**
Simon Morlat's avatar
Simon Morlat committed
687
 * Creates a presence note.
Ghislain MARY's avatar
Ghislain MARY committed
688 689 690 691 692 693
 * @param[in] content The content of the note to be created.
 * @param[in] lang The language of the note to be created. Can be NULL if no language is to be specified for the note.
 * @returns The created presence note, NULL on error.
 */
LINPHONE_PUBLIC LinphonePresenceNote * linphone_presence_note_new(const char *content, const char *lang);

694
/**
Simon Morlat's avatar
Simon Morlat committed
695
 * Gets the content of a presence note.
696 697 698 699 700
 * @param[in] note A pointer to the #LinphonePresenceNote for which to get the content.
 * @return A pointer to the content of the presence note.
 */
LINPHONE_PUBLIC const char * linphone_presence_note_get_content(const LinphonePresenceNote *note);

Ghislain MARY's avatar
Ghislain MARY committed
701
/**
Simon Morlat's avatar
Simon Morlat committed
702
 * Sets the content of a presence note.
Ghislain MARY's avatar
Ghislain MARY committed
703 704 705 706 707 708
 * @param[in] note The #LinphonePresenceNote object for which to set the content.
 * @param[in] content The content of the note.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_note_set_content(LinphonePresenceNote *note, const char *content);

709
/**
Simon Morlat's avatar
Simon Morlat committed
710
 * Gets the language of a presence note.
711 712 713 714 715
 * @param[in] note A pointer to the #LinphonePresenceNote for which to get the language.
 * @return A pointer to the language string of the presence note, or NULL if no language is specified.
 */
LINPHONE_PUBLIC const char * linphone_presence_note_get_lang(const LinphonePresenceNote *note);

Ghislain MARY's avatar
Ghislain MARY committed
716
/**
Simon Morlat's avatar
Simon Morlat committed
717
 * Sets the language of a presence note.
Ghislain MARY's avatar
Ghislain MARY committed
718 719 720 721 722 723
 * @param[in] note The #LinphonePresenceNote object for which to set the language.
 * @param[in] lang The language of the note.
 * @return 0 if successful, a value < 0 in case of error.
 */
LINPHONE_PUBLIC int linphone_presence_note_set_lang(LinphonePresenceNote *note, const char *lang);

724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784

/*****************************************************************************
 * PRESENCE INTERNAL FUNCTIONS FOR WRAPPERS IN OTHER PROGRAMMING LANGUAGES   *
 ****************************************************************************/

/**
 * Increase the reference count of the #LinphonePresenceModel object.
 * @param[in] model The #LinphonePresenceModel object for which the reference count is to be increased.
 * @return The #LinphonePresenceModel object with the increased reference count.
 */
LinphonePresenceModel * linphone_presence_model_ref(LinphonePresenceModel *model);

/**
 * Decrease the reference count of the #LinphonePresenceModel object and destroy it if it reaches 0.
 * @param[in] model The #LinphonePresenceModel object for which the reference count is to be decreased.
 * @return The #LinphonePresenceModel object if the reference count is still positive, NULL if the object has been destroyed.
 */
LinphonePresenceModel * linphone_presence_model_unref(LinphonePresenceModel *model);

/**
 * Sets the user data of a #LinphonePresenceModel object.
 * @param[in] model The #LinphonePresenceModel object for which to set the user data.
 * @param[in] user_data A pointer to the user data to set.
 */
void linphone_presence_model_set_user_data(LinphonePresenceModel *model, void *user_data);

/**
 * Gets the user data of a #LinphonePresenceModel object.
 * @param[in] model The #LinphonePresenceModel object for which to get the user data.
 * @return A pointer to the user data.
 */
void * linphone_presence_model_get_user_data(LinphonePresenceModel *model);

/**
 * Increase the reference count of the #LinphonePresenceService object.
 * @param[in] service The #LinphonePresenceService object for which the reference count is to be increased.
 * @return The #LinphonePresenceService object with the increased reference count.
 */
LinphonePresenceService * linphone_presence_service_ref(LinphonePresenceService *service);

/**
 * Decrease the reference count of the #LinphonePresenceService object and destroy it if it reaches 0.
 * @param[in] service The #LinphonePresenceService object for which the reference count is to be decreased.
 * @return The #LinphonePresenceService object if the reference count is still positive, NULL if the object has been destroyed.
 */
LinphonePresenceService * linphone_presence_service_unref(LinphonePresenceService *service);

/**
 * Sets the user data of a #LinphonePresenceService object.
 * @param[in] service The #LinphonePresenceService object for which to set the user data.
 * @param[in] user_data A pointer to the user data to set.
 */
void linphone_presence_service_set_user_data(LinphonePresenceService *service, void *user_data);

/**
 * Gets the user data of a #LinphonePresenceService object.
 * @param[in] service The #LinphonePresenceService object for which to get the user data.
 * @return A pointer to the user data.
 */
void * linphone_presence_service_get_user_data(LinphonePresenceService *service);

785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812
/**
 * Increase the reference count of the #LinphonePresencePerson object.
 * @param[in] person The #LinphonePresencePerson object for which the reference count is to be increased.
 * @return The #LinphonePresencePerson object with the increased reference count.
 */
LinphonePresencePerson * linphone_presence_person_ref(LinphonePresencePerson *person);

/**
 * Decrease the reference count of the #LinphonePresencePerson object and destroy it if it reaches 0.
 * @param[in] person The #LinphonePresencePerson object for which the reference count is to be decreased.
 * @return The #LinphonePresencePerson object if the reference count is still positive, NULL if the object has been destroyed.
 */
LinphonePresencePerson * linphone_presence_person_unref(LinphonePresencePerson *person);

/**
 * Sets the user data of a #LinphonePresencePerson object.
 * @param[in] person The #LinphonePresencePerson object for which to set the user data.
 * @param[in] user_data A pointer to the user data to set.
 */
void linphone_presence_person_set_user_data(LinphonePresencePerson *person, void *user_data);

/**
 * Gets the user data of a #LinphonePresencePerson object.
 * @param[in] person The #LinphonePresencePerson object for which to get the user data.
 * @return A pointer to the user data.
 */
void * linphone_presence_person_get_user_data(LinphonePresencePerson *person);

813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840
/**
 * Increase the reference count of the #LinphonePresenceActivity object.
 * @param[in] activity The #LinphonePresenceActivity object for which the reference count is to be increased.
 * @return The #LinphonePresenceActivity object with the increased reference count.
 */
LinphonePresenceActivity * linphone_presence_activity_ref(LinphonePresenceActivity *activity);

/**
 * Decrease the reference count of the #LinphonePresenceActivity object and destroy it if it reaches 0.
 * @param[in] activity The #LinphonePresenceActivity object for which the reference count is to be decreased.
 * @return The #LinphonePresenceActivity object if the reference count is still positive, NULL if the object has been destroyed.
 */
LinphonePresenceActivity * linphone_presence_activity_unref(LinphonePresenceActivity *activity);

/**
 * Sets the user data of a #LinphonePresenceActivity object.
 * @param[in] activity The #LinphonePresenceActivity object for which to set the user data.
 * @param[in] user_data A pointer to the user data to set.
 */
void linphone_presence_activity_set_user_data(LinphonePresenceActivity *activity, void *user_data);

/**
 * Gets the user data of a #LinphonePresenceActivity object.
 * @param[in] activity The #LinphonePresenceActivity object for which to get the user data.
 * @return A pointer to the user data.
 */
void * linphone_presence_activity_get_user_data(LinphonePresenceActivity *activity);

Ghislain MARY's avatar
Ghislain MARY committed
841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868
/**
 * Increase the reference count of the #LinphonePresenceNote object.
 * @param[in] note The #LinphonePresenceNote object for which the reference count is to be increased.
 * @return The #LinphonePresenceNote object with the increased reference count.
 */
LinphonePresenceNote * linphone_presence_note_ref(LinphonePresenceNote *note);

/**
 * Decrease the reference count of the #LinphonePresenceNote object and destroy it if it reaches 0.
 * @param[in] note The #LinphonePresenceNote object for which the reference count is to be decreased.
 * @return The #LinphonePresenceNote object if the reference count is still positive, NULL if the object has been destroyed.
 */
LinphonePresenceNote * linphone_presence_note_unref(LinphonePresenceNote *note);

/**
 * Sets the user data of a #LinphonePresenceNote object.
 * @param[in] note The #LinphonePresenceNote object for which to set the user data.
 * @param[in] user_data A pointer to the user data to set.
 */
void linphone_presence_note_set_user_data(LinphonePresenceNote *note, void *user_data);

/**
 * Gets the user data of a #LinphonePresenceNote object.
 * @param[in] note The #LinphonePresenceNote object for which to get the user data.
 * @return A pointer to the user data.
 */
void * linphone_presence_note_get_user_data(LinphonePresenceNote *note);

869 870 871 872 873

/**
 * @}
 */

874 875 876 877 878 879

#ifdef __cplusplus
}
#endif

#endif /* LINPHONEPRESENCE_H_ */