core.h 209 KB
Newer Older
aymeric's avatar
aymeric committed
1 2
/*
linphone
3
Copyright (C) 2000 - 2010 Simon MORLAT (simon.morlat@linphone.org)
aymeric's avatar
aymeric committed
4 5 6 7 8 9 10 11 12 13 14 15 16

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.
aymeric's avatar
aymeric committed
18 19 20 21 22 23 24
*/
#ifndef LINPHONECORE_H
#define LINPHONECORE_H

#include "ortp/ortp.h"
#include "ortp/payloadtype.h"
#include "mediastreamer2/mscommon.h"
smorlat's avatar
smorlat committed
25
#include "mediastreamer2/msvideo.h"
Sylvain Berfini's avatar
Sylvain Berfini committed
26
#include "mediastreamer2/mediastream.h"
27
#include "mediastreamer2/bitratecontrol.h"
28
#include "linphone/sipsetup.h"
29
#include "linphone/lpconfig.h"
Ghislain MARY's avatar
Ghislain MARY committed
30

smorlat's avatar
smorlat committed
31
#define LINPHONE_IPADDR_SIZE 64
smorlat's avatar
smorlat committed
32
#define LINPHONE_HOSTNAME_SIZE 128
smorlat's avatar
smorlat committed
33

jehan's avatar
jehan committed
34
#ifndef LINPHONE_PUBLIC
Simon Morlat's avatar
Simon Morlat committed
35
#define LINPHONE_PUBLIC MS2_PUBLIC
Sylvain Berfini's avatar
Sylvain Berfini committed
36 37
#endif

38
#ifndef LINPHONE_DEPRECATED
Simon Morlat's avatar
Simon Morlat committed
39
#define LINPHONE_DEPRECATED MS2_DEPRECATED
40
#endif
jehan's avatar
jehan committed
41 42


aymeric's avatar
aymeric committed
43 44 45 46 47
#ifdef __cplusplus
extern "C" {
#endif

struct _LinphoneCore;
48
struct _LinphoneChatRoom;
49 50 51
struct _LinphoneAuthInfo;
struct _SipSetupContext;
struct _LinphoneInfoMessage;
52

jehan's avatar
jehan committed
53 54 55 56 57
/**
 * Linphone core main object created by function linphone_core_new() .
 * @ingroup initializing
 */
typedef struct _LinphoneCore LinphoneCore;
aymeric's avatar
aymeric committed
58

59

60 61 62 63 64 65 66 67 68 69 70
/**
 * Disable a sip transport
 * Use with #LCSipTransports
 * @ingroup initializing
 */
#define LC_SIP_TRANSPORT_DISABLED 0
/**
 * Randomly chose a sip port for this transport
 * Use with #LCSipTransports
 * @ingroup initializing
 */
Simon Morlat's avatar
Simon Morlat committed
71 72 73 74 75 76 77 78
#define LC_SIP_TRANSPORT_RANDOM (-1)

/**
 * Don't create any server socket for this transport, ie don't bind on any port.
 * Use with #LCSipTransports
 * @ingroup initializing
**/
#define LC_SIP_TRANSPORT_DONTBIND (-2)
79

jehan's avatar
jehan committed
80 81
/**
 * Linphone core SIP transport ports.
Simon Morlat's avatar
Simon Morlat committed
82
 * Special values LC_SIP_TRANSPORT_RANDOM, LC_SIP_TRANSPORT_RANDOM, #define LC_SIP_TRANSPORT_DONTBIND can be used.
jehan's avatar
jehan committed
83 84 85
 * Use with #linphone_core_set_sip_transports
 * @ingroup initializing
 */
jehan's avatar
jehan committed
86
typedef struct _LCSipTransports{
jehan's avatar
jehan committed
87
	/**
Simon Morlat's avatar
Simon Morlat committed
88 89
	 * SIP/UDP port.
	 **/
90
	int udp_port;
jehan's avatar
jehan committed
91
	/**
Simon Morlat's avatar
Simon Morlat committed
92
	 * SIP/TCP port
jehan's avatar
jehan committed
93
	 * */
94
	int tcp_port;
jehan's avatar
jehan committed
95
	/**
Simon Morlat's avatar
Simon Morlat committed
96
	 * SIP/DTLS port
jehan's avatar
jehan committed
97
	 * */
98
	int dtls_port;
jehan's avatar
jehan committed
99
	/**
Simon Morlat's avatar
Simon Morlat committed
100
	 * SIP/TLS port
jehan's avatar
jehan committed
101
	 * */
102
	int tls_port;
jehan's avatar
jehan committed
103 104
} LCSipTransports;

105

106 107
/**
 * Enum describing transport type for LinphoneAddress.
108
 * @ingroup linphone_address
109 110 111 112 113 114 115 116 117
**/
enum _LinphoneTransportType{
	LinphoneTransportUdp,
	LinphoneTransportTcp,
	LinphoneTransportTls,
	LinphoneTransportDtls
};
/*this enum MUST be kept in sync with the SalTransport from sal.h*/

118 119 120 121
/**
 * Typedef for transport type enum.
 * @ingroup linphone_address
**/
122 123
typedef enum _LinphoneTransportType LinphoneTransportType;

124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
/**
 * Enum describing the stream types.
 * @ingroup initializing
**/
enum _LinphoneStreamType {
	LinphoneStreamTypeAudio,
	LinphoneStreamTypeVideo,
	LinphoneStreamTypeText,
	LinphoneStreamTypeUnknown /* WARNING: Make sure this value remains the last one in the list */
};

/**
 * Enum describing the stream types.
 * @ingroup initializing
**/
typedef enum _LinphoneStreamType LinphoneStreamType;
140

141
/**
142
 * Function returning a human readable value for LinphoneStreamType.
143 144
 * @ingroup initializing
 **/
145

146
LINPHONE_PUBLIC const char *linphone_stream_type_to_string(const LinphoneStreamType);
147

148 149
typedef struct belle_sip_dict LinphoneDictionary;

150
#include "linphone/error_info.h"
151

152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
/**
 * Enum describing the authentication methods
 * @ingroup network_parameters
**/
enum _LinphoneAuthMethod {
	LinphoneAuthHttpDigest, /* Digest authentication requested */
	LinphoneAuthTls, /* Client certificate requested */
};

/**
 * Typedef for authentication methods enum.
 * @ingroup network_parameters
**/
typedef enum _LinphoneAuthMethod LinphoneAuthMethod;

167
/* linphone dictionary */
168
LINPHONE_PUBLIC LinphoneDictionary* linphone_dictionary_new(void);
Ghislain MARY's avatar
Ghislain MARY committed
169 170 171
LINPHONE_PUBLIC LinphoneDictionary * linphone_dictionary_clone(const LinphoneDictionary* src);
LINPHONE_PUBLIC LinphoneDictionary * linphone_dictionary_ref(LinphoneDictionary* obj);
LINPHONE_PUBLIC void linphone_dictionary_unref(LinphoneDictionary* obj);
172 173 174 175 176 177 178 179
LINPHONE_PUBLIC void linphone_dictionary_set_int(LinphoneDictionary* obj, const char* key, int value);
LINPHONE_PUBLIC int linphone_dictionary_get_int(LinphoneDictionary* obj, const char* key, int default_value);
LINPHONE_PUBLIC void linphone_dictionary_set_string(LinphoneDictionary* obj, const char* key, const char*value);
LINPHONE_PUBLIC const char* linphone_dictionary_get_string(LinphoneDictionary* obj, const char* key, const char* default_value);
LINPHONE_PUBLIC void linphone_dictionary_set_int64(LinphoneDictionary* obj, const char* key, int64_t value);
LINPHONE_PUBLIC int64_t linphone_dictionary_get_int64(LinphoneDictionary* obj, const char* key, int64_t default_value);
LINPHONE_PUBLIC int linphone_dictionary_remove(LinphoneDictionary* obj, const char* key);
LINPHONE_PUBLIC void linphone_dictionary_clear(LinphoneDictionary* obj);
180
LINPHONE_PUBLIC int linphone_dictionary_haskey(const LinphoneDictionary* obj, const char* key);
181 182 183 184 185 186
LINPHONE_PUBLIC void linphone_dictionary_foreach( const LinphoneDictionary* obj, void (*apply_func)(const char*key, void* value, void* userdata), void* userdata);
/**
 * Converts a config section into a dictionary.
 * @return a #LinphoneDictionary with all the keys from a section, or NULL if the section doesn't exist
 * @ingroup misc
 */
Ghislain MARY's avatar
Ghislain MARY committed
187
LINPHONE_PUBLIC LinphoneDictionary* lp_config_section_to_dict( const LpConfig* lpconfig, const char* section );
188 189 190 191 192 193

/**
 * Loads a dictionary into a section of the lpconfig. If the section doesn't exist it is created.
 * Overwrites existing keys, creates non-existing keys.
 * @ingroup misc
 */
Ghislain MARY's avatar
Ghislain MARY committed
194
LINPHONE_PUBLIC void lp_config_load_dict_to_section( LpConfig* lpconfig, const char* section, const LinphoneDictionary* dict);
195 196


197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225
/**
 * @addtogroup media_parameters
 * @{
**/

/**
 * Object representing an RTP payload type.
 */
typedef PayloadType LinphonePayloadType;

/**
 * Get the type of payload.
 * @param[in] pt LinphonePayloadType object
 * @return The type of payload.
 */
LINPHONE_PUBLIC int linphone_payload_type_get_type(const LinphonePayloadType *pt);

/**
 * Get the normal bitrate in bits/s.
 * @param[in] pt LinphonePayloadType object
 * @return The normal bitrate in bits/s.
 */
LINPHONE_PUBLIC int linphone_payload_type_get_normal_bitrate(const LinphonePayloadType *pt);

/**
 * Get the mime type.
 * @param[in] pt LinphonePayloadType object
 * @return The mime type.
 */
226
LINPHONE_PUBLIC const char * linphone_payload_type_get_mime_type(const LinphonePayloadType *pt);
227 228 229 230 231 232 233 234

/**
 * Get the number of channels.
 * @param[in] pt LinphonePayloadType object
 * @return The number of channels.
 */
LINPHONE_PUBLIC int linphone_payload_type_get_channels(const LinphonePayloadType *pt);

235

236 237 238 239 240 241 242 243 244 245 246 247 248 249
/**
 * Enum describing RTP AVPF activation modes.
**/
enum _LinphoneAVPFMode{
	LinphoneAVPFDefault=-1, /**<Use default value defined at upper level*/
	LinphoneAVPFDisabled, /**<AVPF is disabled*/
	LinphoneAVPFEnabled /**<AVPF is enabled */
};

/**
 * Enum describing RTP AVPF activation modes.
**/
typedef enum _LinphoneAVPFMode  LinphoneAVPFMode;

250 251 252 253 254 255
/**
 * Enum describing type of media encryption types.
**/
enum _LinphoneMediaEncryption {
	LinphoneMediaEncryptionNone, /**< No media encryption is used */
	LinphoneMediaEncryptionSRTP, /**< Use SRTP media encryption */
johan's avatar
johan committed
256 257
	LinphoneMediaEncryptionZRTP, /**< Use ZRTP media encryption */
	LinphoneMediaEncryptionDTLS /**< Use DTLS media encryption */
258 259 260 261 262 263 264 265 266 267 268 269
};

/**
 * Enum describing type of media encryption types.
**/
typedef enum _LinphoneMediaEncryption LinphoneMediaEncryption;

/**
 * Convert enum member to string.
**/
LINPHONE_PUBLIC const char *linphone_media_encryption_to_string(LinphoneMediaEncryption menc);

270 271 272 273
/**
 * @}
**/

274

Simon Morlat's avatar
Simon Morlat committed
275 276 277
/*
 * Note for developers: this enum must be kept synchronized with the SalPrivacy enum declared in sal.h
 */
Simon Morlat's avatar
Simon Morlat committed
278
/**
jehan's avatar
jehan committed
279
 * @ingroup call_control
jehan's avatar
jehan committed
280
 * Defines privacy policy to apply as described by rfc3323
Simon Morlat's avatar
Simon Morlat committed
281
**/
jehan's avatar
jehan committed
282 283
typedef enum _LinphonePrivacy {
	/**
Simon Morlat's avatar
Simon Morlat committed
284
	 * Privacy services must not perform any privacy function
jehan's avatar
jehan committed
285
	 */
Simon Morlat's avatar
Simon Morlat committed
286
	LinphonePrivacyNone=0x0,
jehan's avatar
jehan committed
287
	/**
jehan's avatar
jehan committed
288
	 * Request that privacy services provide a user-level privacy
Simon Morlat's avatar
Simon Morlat committed
289 290
	 * function.
	 * With this mode, "from" header is hidden, usually replaced by  From: "Anonymous" <sip:anonymous@anonymous.invalid>
jehan's avatar
jehan committed
291
	 */
jehan's avatar
jehan committed
292
	LinphonePrivacyUser=0x1,
jehan's avatar
jehan committed
293
	/**
jehan's avatar
jehan committed
294
	 * Request that privacy services modify headers that cannot
Simon Morlat's avatar
Simon Morlat committed
295
	 * be set arbitrarily by the user (Contact/Via).
jehan's avatar
jehan committed
296
	 */
jehan's avatar
jehan committed
297
	LinphonePrivacyHeader=0x2,
Simon Morlat's avatar
Simon Morlat committed
298
	/**
jehan's avatar
jehan committed
299
	 *  Request that privacy services provide privacy for session
Simon Morlat's avatar
Simon Morlat committed
300 301
	 * media
	 */
jehan's avatar
jehan committed
302 303 304 305
	LinphonePrivacySession=0x4,
	/**
	 * rfc3325
	 * The presence of this privacy type in
Simon Morlat's avatar
Simon Morlat committed
306 307 308 309 310
	 * a Privacy header field indicates that the user would like the Network
	 * Asserted Identity to be kept private with respect to SIP entities
	 * outside the Trust Domain with which the user authenticated.  Note
	 * that a user requesting multiple types of privacy MUST include all of
	 * the requested privacy types in its Privacy header field value
jehan's avatar
jehan committed
311 312 313 314 315
	 *
	 */
	LinphonePrivacyId=0x8,
	/**
	 * Privacy service must perform the specified services or
Simon Morlat's avatar
Simon Morlat committed
316
	 * fail the request
jehan's avatar
jehan committed
317 318
	 *
	 **/
Simon Morlat's avatar
Simon Morlat committed
319
	LinphonePrivacyCritical=0x10,
Guillaume BIENKOWSKI's avatar
Guillaume BIENKOWSKI committed
320

Simon Morlat's avatar
Simon Morlat committed
321
	/**
Simon Morlat's avatar
Simon Morlat committed
322
	 * Special keyword to use privacy as defined either globally or by proxy using linphone_proxy_config_set_privacy()
Simon Morlat's avatar
Simon Morlat committed
323 324
	 */
	LinphonePrivacyDefault=0x8000,
jehan's avatar
jehan committed
325
} LinphonePrivacy;
jehan's avatar
jehan committed
326 327 328 329 330
/*
 * a mask  of #LinphonePrivacy values
 * */
typedef unsigned int LinphonePrivacyMask;

Simon Morlat's avatar
Simon Morlat committed
331 332

LINPHONE_PUBLIC const char* linphone_privacy_to_string(LinphonePrivacy privacy);
Ghislain MARY's avatar
Ghislain MARY committed
333 334


335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376
/**
 * Player interface.
 * @ingroup call_control
**/
typedef struct _LinphonePlayer LinphonePlayer;

/**
 * Callback for notifying end of play (file).
 * @param obj the LinphonePlayer
 * @param user_data the user_data provided when calling linphone_player_open().
 * @ingroup call_control
**/
typedef void (*LinphonePlayerEofCallback)(struct _LinphonePlayer *obj, void *user_data);

LINPHONE_PUBLIC int linphone_player_open(LinphonePlayer *obj, const char *filename, LinphonePlayerEofCallback, void *user_data);
LINPHONE_PUBLIC int linphone_player_start(LinphonePlayer *obj);
LINPHONE_PUBLIC int linphone_player_pause(LinphonePlayer *obj);
LINPHONE_PUBLIC int linphone_player_seek(LinphonePlayer *obj, int time_ms);
LINPHONE_PUBLIC MSPlayerState linphone_player_get_state(LinphonePlayer *obj);
LINPHONE_PUBLIC int linphone_player_get_duration(LinphonePlayer *obj);
LINPHONE_PUBLIC int linphone_player_get_current_position(LinphonePlayer *obj);
LINPHONE_PUBLIC void linphone_player_close(LinphonePlayer *obj);
LINPHONE_PUBLIC void linphone_player_destroy(LinphonePlayer *obj);

/**
 * Create an independent media file player.
 * This player support WAVE and MATROSKA formats.
 * @param lc A LinphoneCore object
 * @param snd_card Playback sound card. If NULL, the sound card set in LinphoneCore will be used
 * @param video_out Video display. If NULL, the video display set in LinphoneCore will be used
 * @param window_id Id of the drawing window. Depend of video out
 * @return A pointer on the new instance. NULL if faild.
 */
LINPHONE_PUBLIC LinphonePlayer *linphone_core_create_local_player(LinphoneCore *lc, MSSndCard *snd_card, const char *video_out, void *window_id);

/**
 * Check whether Matroksa format is supported by the player
 * @return TRUE if it is supported
 */
LINPHONE_PUBLIC bool_t linphone_local_player_matroska_supported(void);


377
#include "linphone/address.h"
378
#include "linphone/buffer.h"
379
#include "linphone/call.h"
Ghislain MARY's avatar
Ghislain MARY committed
380 381
#include "linphone/call_log.h"
#include "linphone/call_params.h"
382 383 384
#include "linphone/content.h"
#include "linphone/event.h"
#include "linphone/linphonefriend.h"
385
#include "linphone/nat_policy.h"
386
#include "linphone/xmlrpc.h"
387
#include "linphone/conference.h"
Ghislain MARY's avatar
Ghislain MARY committed
388 389 390 391 392 393 394 395 396 397

/**
 * Create a #LinphoneAddress object by parsing the user supplied address, given as a string.
 * @param[in] lc #LinphoneCore object
 * @param[in] address String containing the user supplied address
 * @return The create #LinphoneAddress object
 * @ingroup linphone_address
 */
LINPHONE_PUBLIC LinphoneAddress * linphone_core_create_address(LinphoneCore *lc, const char *address);

Simon Morlat's avatar
Simon Morlat committed
398 399 400 401 402
/**
 * The LinphoneInfoMessage is an object representing an informational message sent or received by the core.
**/
typedef struct _LinphoneInfoMessage LinphoneInfoMessage;

403 404
LINPHONE_PUBLIC LinphoneInfoMessage *linphone_core_create_info_message(LinphoneCore*lc);
LINPHONE_PUBLIC int linphone_call_send_info_message(struct _LinphoneCall *call, const LinphoneInfoMessage *info);
Simon Morlat's avatar
Simon Morlat committed
405
LINPHONE_PUBLIC void linphone_info_message_add_header(LinphoneInfoMessage *im, const char *name, const char *value);
Simon Morlat's avatar
Simon Morlat committed
406
LINPHONE_PUBLIC const char *linphone_info_message_get_header(const LinphoneInfoMessage *im, const char *name);
Simon Morlat's avatar
Simon Morlat committed
407
LINPHONE_PUBLIC void linphone_info_message_set_content(LinphoneInfoMessage *im,  const LinphoneContent *content);
Simon Morlat's avatar
Simon Morlat committed
408
LINPHONE_PUBLIC const LinphoneContent * linphone_info_message_get_content(const LinphoneInfoMessage *im);
Simon Morlat's avatar
Simon Morlat committed
409
LINPHONE_PUBLIC void linphone_info_message_destroy(LinphoneInfoMessage *im);
410
LINPHONE_PUBLIC LinphoneInfoMessage *linphone_info_message_copy(const LinphoneInfoMessage *orig);
Simon Morlat's avatar
Simon Morlat committed
411

Simon Morlat's avatar
Simon Morlat committed
412 413


414 415
/**
 * Structure describing policy regarding video streams establishments.
Simon Morlat's avatar
Simon Morlat committed
416
 * @ingroup media_parameters
417 418
**/
struct _LinphoneVideoPolicy{
Guillaume BIENKOWSKI's avatar
Guillaume BIENKOWSKI committed
419
	bool_t automatically_initiate; /**<Whether video shall be automatically proposed for outgoing calls.*/
420 421 422 423
	bool_t automatically_accept; /**<Whether video shall be automatically accepted for incoming calls*/
	bool_t unused[2];
};

Simon Morlat's avatar
Simon Morlat committed
424 425 426 427
/**
 * Structure describing policy regarding video streams establishments.
 * @ingroup media_parameters
**/
428 429
typedef struct _LinphoneVideoPolicy LinphoneVideoPolicy;

430

Yann Diorcet's avatar
Yann Diorcet committed
431 432


Simon Morlat's avatar
Simon Morlat committed
433 434 435 436 437
/**
 * @addtogroup call_misc
 * @{
**/

438 439 440
#define LINPHONE_CALL_STATS_AUDIO ((int)LinphoneStreamTypeAudio)
#define LINPHONE_CALL_STATS_VIDEO ((int)LinphoneStreamTypeVideo)
#define LINPHONE_CALL_STATS_TEXT  ((int)LinphoneStreamTypeText)
Yann Diorcet's avatar
Yann Diorcet committed
441

442 443 444 445 446
/**
 * Enum describing ICE states.
 * @ingroup initializing
**/
enum _LinphoneIceState{
Simon Morlat's avatar
Simon Morlat committed
447
	LinphoneIceStateNotActivated, /**< ICE has not been activated for this call or stream*/
Ghislain MARY's avatar
Ghislain MARY committed
448
	LinphoneIceStateFailed, /**< ICE processing has failed */
449 450 451 452 453 454 455 456 457 458 459 460
	LinphoneIceStateInProgress, /**< ICE process is in progress */
	LinphoneIceStateHostConnection, /**< ICE has established a direct connection to the remote host */
	LinphoneIceStateReflexiveConnection, /**< ICE has established a connection to the remote host through one or several NATs */
	LinphoneIceStateRelayConnection /**< ICE has established a connection through a relay */
};

/**
 * Enum describing Ice states.
 * @ingroup initializing
**/
typedef enum _LinphoneIceState LinphoneIceState;

461 462
LINPHONE_PUBLIC const char *linphone_ice_state_to_string(LinphoneIceState state);

Yann Diorcet's avatar
Yann Diorcet committed
463 464 465 466 467 468 469 470 471 472 473 474
/**
 * Enum describing uPnP states.
 * @ingroup initializing
**/
enum _LinphoneUpnpState{
	LinphoneUpnpStateIdle, /**< uPnP is not activate */
	LinphoneUpnpStatePending, /**< uPnP process is in progress */
	LinphoneUpnpStateAdding,   /**< Internal use: Only used by port binding */
	LinphoneUpnpStateRemoving, /**< Internal use: Only used by port binding */
	LinphoneUpnpStateNotAvailable,  /**< uPnP is not available */
	LinphoneUpnpStateOk, /**< uPnP is enabled */
	LinphoneUpnpStateKo, /**< uPnP processing has failed */
Yann Diorcet's avatar
Yann Diorcet committed
475
	LinphoneUpnpStateBlacklisted, /**< IGD router is blacklisted */
Yann Diorcet's avatar
Yann Diorcet committed
476 477 478 479 480 481 482 483
};

/**
 * Enum describing uPnP states.
 * @ingroup initializing
**/
typedef enum _LinphoneUpnpState LinphoneUpnpState;

484

485 486 487 488
/**
 * Enum describing Ip family.
 * @ingroup initializing
**/
Erwan Croze's avatar
Erwan Croze committed
489 490 491 492
enum _LinphoneAddressFamily {
	LinphoneAddressFamilyInet, /* IpV4 */
	LinphoneAddressFamilyInet6, /* IpV6 */
	LinphoneAddressFamilyUnspec, /* Unknown */
493 494 495 496 497 498
};

/**
 * Enum describing Ip family.
 * @ingroup initializing
**/
Erwan Croze's avatar
Erwan Croze committed
499
typedef enum _LinphoneAddressFamily LinphoneAddressFamily;
500

Simon Morlat's avatar
Simon Morlat committed
501 502 503
/**
 * @}
**/
Yann Diorcet's avatar
Yann Diorcet committed
504

505 506
#include "linphone/call_stats.h"

Sylvain Berfini's avatar
Sylvain Berfini committed
507 508
LINPHONE_PUBLIC const LinphoneCallStats *linphone_call_get_audio_stats(LinphoneCall *call);
LINPHONE_PUBLIC const LinphoneCallStats *linphone_call_get_video_stats(LinphoneCall *call);
509
LINPHONE_PUBLIC const LinphoneCallStats *linphone_call_get_text_stats(LinphoneCall *call);
Yann Diorcet's avatar
Yann Diorcet committed
510

511 512 513 514 515 516
/**
 * Get the remote address of the current call.
 * @param[in] lc LinphoneCore object.
 * @return The remote address of the current call or NULL if there is no current call.
 * @ingroup call_control
 */
517
LINPHONE_PUBLIC const LinphoneAddress * linphone_core_get_current_call_remote_address(LinphoneCore *lc);
518

519

Simon Morlat's avatar
Simon Morlat committed
520
/*keep this in sync with mediastreamer2/msvolume.h*/
Simon Morlat's avatar
Simon Morlat committed
521 522 523 524 525 526

/**
 * Lowest volume measurement that can be returned by linphone_call_get_play_volume() or linphone_call_get_record_volume(), corresponding to pure silence.
 * @ingroup call_misc
**/
#define LINPHONE_VOLUME_DB_LOWEST (-120)
Simon Morlat's avatar
Simon Morlat committed
527

smorlat's avatar
smorlat committed
528 529 530 531
/**
 * @addtogroup proxies
 * @{
**/
532

smorlat's avatar
smorlat committed
533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548
/**
 * The LinphoneProxyConfig object represents a proxy configuration to be used
 * by the LinphoneCore object.
 * Its fields must not be used directly in favour of the accessors methods.
 * Once created and filled properly the LinphoneProxyConfig can be given to
 * LinphoneCore with linphone_core_add_proxy_config().
 * This will automatically triggers the registration, if enabled.
 *
 * The proxy configuration are persistent to restarts because they are saved
 * in the configuration file. As a consequence, after linphone_core_new() there
 * might already be a list of configured proxy that can be examined with
 * linphone_core_get_proxy_config_list().
 *
 * The default proxy (see linphone_core_set_default_proxy() ) is the one of the list
 * that is used by default for calls.
**/
549
typedef struct _LinphoneProxyConfig LinphoneProxyConfig;
aymeric's avatar
aymeric committed
550

551 552 553 554
/**
 * LinphoneRegistrationState describes proxy registration states.
**/
typedef enum _LinphoneRegistrationState{
Simon Morlat's avatar
Simon Morlat committed
555 556 557 558 559
	LinphoneRegistrationNone, /**<Initial state for registrations */
	LinphoneRegistrationProgress, /**<Registration is in progress */
	LinphoneRegistrationOk,	/**< Registration is successful */
	LinphoneRegistrationCleared, /**< Unregistration succeeded */
	LinphoneRegistrationFailed	/**<Registration failed */
560 561
}LinphoneRegistrationState;

jehan's avatar
jehan committed
562 563 564 565
/**
 * Human readable version of the #LinphoneRegistrationState
 * @param cs sate
 */
566
LINPHONE_PUBLIC const char *linphone_registration_state_to_string(LinphoneRegistrationState cs);
567

568 569 570 571
/**
 * @}
 */

smorlat's avatar
smorlat committed
572
/**
573 574
 * @addtogroup authentication
 * @{
Ghislain MARY's avatar
Ghislain MARY committed
575 576 577
 */

/**
smorlat's avatar
smorlat committed
578 579 580 581 582 583 584 585 586 587
 * Object holding authentication information.
 *
 * @note The object's fields should not be accessed directly. Prefer using
 * the accessor methods.
 *
 * In most case, authentication information consists of a username and password.
 * Sometimes, a userid is required by proxy, and realm can be useful to discriminate
 * different SIP domains.
 *
 * Once created and filled, a LinphoneAuthInfo must be added to the LinphoneCore in
588
 * order to become known and used automatically when needed.
smorlat's avatar
smorlat committed
589 590 591 592 593 594
 * Use linphone_core_add_auth_info() for that purpose.
 *
 * The LinphoneCore object can take the initiative to request authentication information
 * when needed to the application through the auth_info_requested callback of the
 * LinphoneCoreVTable structure.
 *
595 596
 * The application can respond to this information request later using
 * linphone_core_add_auth_info(). This will unblock all pending authentication
smorlat's avatar
smorlat committed
597 598 599
 * transactions and retry them with authentication headers.
 *
**/
600
typedef struct _LinphoneAuthInfo LinphoneAuthInfo;
aymeric's avatar
aymeric committed
601

602
/**
Ghislain MARY's avatar
Ghislain MARY committed
603
 * Creates a #LinphoneAuthInfo object with supplied information.
604 605 606 607 608 609 610 611 612
 * The object can be created empty, that is with all arguments set to NULL.
 * Username, userid, password, realm and domain can be set later using specific methods.
 * At the end, username and passwd (or ha1) are required.
 * @param username The username that needs to be authenticated
 * @param userid The userid used for authenticating (use NULL if you don't know what it is)
 * @param passwd The password in clear text
 * @param ha1 The ha1-encrypted password if password is not given in clear text.
 * @param realm The authentication domain (which can be larger than the sip domain. Unfortunately many SIP servers don't use this parameter.
 * @param domain The SIP domain for which this authentication information is valid, if it has to be restricted for a single SIP domain.
Ghislain MARY's avatar
Ghislain MARY committed
613
 * @return A #LinphoneAuthInfo object. linphone_auth_info_destroy() must be used to destroy it when no longer needed. The LinphoneCore makes a copy of LinphoneAuthInfo
614 615
 * passed through linphone_core_add_auth_info().
**/
616
LINPHONE_PUBLIC LinphoneAuthInfo *linphone_auth_info_new(const char *username, const char *userid,
617 618
	const char *passwd, const char *ha1,const char *realm, const char *domain);

619
/**
620
 * Instantiates a new auth info with values from source.
Ghislain MARY's avatar
Ghislain MARY committed
621 622
 * @param[in] source The #LinphoneAuthInfo object to be cloned
 * @return The newly created #LinphoneAuthInfo object.
623
 */
624
LINPHONE_PUBLIC LinphoneAuthInfo *linphone_auth_info_clone(const LinphoneAuthInfo* source);
625 626 627

/**
 * Sets the password.
Ghislain MARY's avatar
Ghislain MARY committed
628
 * @param[in] info The #LinphoneAuthInfo object
629 630
 * @param[in] passwd The password.
**/
Ghislain MARY's avatar
Ghislain MARY committed
631
LINPHONE_PUBLIC void linphone_auth_info_set_passwd(LinphoneAuthInfo *info, const char *passwd);
632 633 634

/**
 * Sets the username.
Ghislain MARY's avatar
Ghislain MARY committed
635
 * @param[in] info The #LinphoneAuthInfo object
636 637
 * @param[in] username The username.
**/
Ghislain MARY's avatar
Ghislain MARY committed
638
LINPHONE_PUBLIC void linphone_auth_info_set_username(LinphoneAuthInfo *info, const char *username);
639 640 641

/**
 * Sets the userid.
Ghislain MARY's avatar
Ghislain MARY committed
642
 * @param[in] info The #LinphoneAuthInfo object
643 644
 * @param[in] userid The userid.
**/
Ghislain MARY's avatar
Ghislain MARY committed
645
LINPHONE_PUBLIC void linphone_auth_info_set_userid(LinphoneAuthInfo *info, const char *userid);
646 647 648

/**
 * Sets the realm.
Ghislain MARY's avatar
Ghislain MARY committed
649
 * @param[in] info The #LinphoneAuthInfo object
650 651
 * @param[in] realm The realm.
**/
Ghislain MARY's avatar
Ghislain MARY committed
652
LINPHONE_PUBLIC void linphone_auth_info_set_realm(LinphoneAuthInfo *info, const char *realm);
653 654 655

/**
 * Sets the domain for which this authentication is valid.
Ghislain MARY's avatar
Ghislain MARY committed
656
 * @param[in] info The #LinphoneAuthInfo object
657 658 659 660
 * @param[in] domain The domain.
 * This should not be necessary because realm is supposed to be unique and sufficient.
 * However, many SIP servers don't set realm correctly, then domain has to be used to distinguish between several SIP account bearing the same username.
**/
661
LINPHONE_PUBLIC void linphone_auth_info_set_domain(LinphoneAuthInfo *info, const char *domain);
662 663 664

/**
 * Sets the ha1.
Ghislain MARY's avatar
Ghislain MARY committed
665
 * @param[in] info The #LinphoneAuthInfo object
666 667
 * @param[in] ha1 The ha1.
**/
Ghislain MARY's avatar
Ghislain MARY committed
668 669
LINPHONE_PUBLIC void linphone_auth_info_set_ha1(LinphoneAuthInfo *info, const char *ha1);

670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697
/**
 * Sets the TLS certificate.
 * @param[in] info The #LinphoneAuthInfo object
 * @param[in] ha1 The TLS certificate.
**/
LINPHONE_PUBLIC void linphone_auth_info_set_tls_cert(LinphoneAuthInfo *info, const char *tls_cert);

/**
 * Sets the TLS key.
 * @param[in] info The #LinphoneAuthInfo object
 * @param[in] ha1 The TLS key.
**/
LINPHONE_PUBLIC void linphone_auth_info_set_tls_key(LinphoneAuthInfo *info, const char *tls_key);

/**
 * Sets the TLS certificate path.
 * @param[in] info The #LinphoneAuthInfo object
 * @param[in] ha1 The TLS certificate path.
**/
LINPHONE_PUBLIC void linphone_auth_info_set_tls_cert_path(LinphoneAuthInfo *info, const char *tls_cert_path);

/**
 * Sets the TLS key path.
 * @param[in] info The #LinphoneAuthInfo object
 * @param[in] ha1 The TLS key path.
**/
LINPHONE_PUBLIC void linphone_auth_info_set_tls_key_path(LinphoneAuthInfo *info, const char *tls_key_path);

698 699 700
/**
 * Gets the username.
 *
Ghislain MARY's avatar
Ghislain MARY committed
701
 * @param[in] info The #LinphoneAuthInfo object
702 703
 * @return The username.
 */
Ghislain MARY's avatar
Ghislain MARY committed
704
LINPHONE_PUBLIC const char *linphone_auth_info_get_username(const LinphoneAuthInfo *info);
705 706 707 708

/**
 * Gets the password.
 *
Ghislain MARY's avatar
Ghislain MARY committed
709
 * @param[in] info The #LinphoneAuthInfo object
710 711
 * @return The password.
 */
Ghislain MARY's avatar
Ghislain MARY committed
712
LINPHONE_PUBLIC const char *linphone_auth_info_get_passwd(const LinphoneAuthInfo *info);
713 714 715 716

/**
 * Gets the userid.
 *
Ghislain MARY's avatar
Ghislain MARY committed
717
 * @param[in] info The #LinphoneAuthInfo object
718 719
 * @return The userid.
 */
Ghislain MARY's avatar
Ghislain MARY committed
720
LINPHONE_PUBLIC const char *linphone_auth_info_get_userid(const LinphoneAuthInfo *info);
721 722 723 724

/**
 * Gets the realm.
 *
Ghislain MARY's avatar
Ghislain MARY committed
725
 * @param[in] info The #LinphoneAuthInfo object
726 727
 * @return The realm.
 */
Ghislain MARY's avatar
Ghislain MARY committed
728
LINPHONE_PUBLIC const char *linphone_auth_info_get_realm(const LinphoneAuthInfo *info);
729 730 731 732

/**
 * Gets the domain.
 *
Ghislain MARY's avatar
Ghislain MARY committed
733
 * @param[in] info The #LinphoneAuthInfo object
734 735
 * @return The domain.
 */
Ghislain MARY's avatar
Ghislain MARY committed
736
LINPHONE_PUBLIC const char *linphone_auth_info_get_domain(const LinphoneAuthInfo *info);
737 738 739 740

/**
 * Gets the ha1.
 *
Ghislain MARY's avatar
Ghislain MARY committed
741
 * @param[in] info The #LinphoneAuthInfo object
742 743
 * @return The ha1.
 */
Ghislain MARY's avatar
Ghislain MARY committed
744
LINPHONE_PUBLIC const char *linphone_auth_info_get_ha1(const LinphoneAuthInfo *info);
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
/**
 * Gets the TLS certificate.
 *
 * @param[in] info The #LinphoneAuthInfo object
 * @return The TLS certificate.
 */
LINPHONE_PUBLIC const char *linphone_auth_info_get_tls_cert(const LinphoneAuthInfo *info);

/**
 * Gets the TLS key.
 *
 * @param[in] info The #LinphoneAuthInfo object
 * @return The TLS key.
 */
LINPHONE_PUBLIC const char *linphone_auth_info_get_tls_key(const LinphoneAuthInfo *info);

/**
 * Gets the TLS certificate path.
 *
 * @param[in] info The #LinphoneAuthInfo object
 * @return The TLS certificate path.
 */
LINPHONE_PUBLIC const char *linphone_auth_info_get_tls_cert_path(const LinphoneAuthInfo *info);

/**
 * Gets the TLS key path.
 *
 * @param[in] info The #LinphoneAuthInfo object
 * @return The TLS key path.
 */
LINPHONE_PUBLIC const char *linphone_auth_info_get_tls_key_path(const LinphoneAuthInfo *info);

aymeric's avatar
aymeric committed
778
/* you don't need those function*/
Ghislain MARY's avatar
Ghislain MARY committed
779 780
LINPHONE_PUBLIC void linphone_auth_info_destroy(LinphoneAuthInfo *info);
LINPHONE_PUBLIC LinphoneAuthInfo * linphone_auth_info_new_from_config_file(LpConfig *config, int pos);
aymeric's avatar
aymeric committed
781

782 783 784 785
/**
 * @}
 */

jehan's avatar
jehan committed
786

787
#include "linphone/account_creator.h"
788
#include "linphone/friendlist.h"
789
#include "linphone/linphone_proxy_config.h"
790 791


jehan's avatar
jehan committed
792 793 794 795
/**
 * @addtogroup chatroom
 * @{
 */
jehan's avatar
jehan committed
796 797

/**
798 799 800 801 802 803
 * An object to handle the callbacks for the handling a LinphoneChatMessage objects.
 */
typedef struct _LinphoneChatMessageCbs LinphoneChatMessageCbs;

/**
 * A chat room message to hold content to be sent.
jehan's avatar
jehan committed
804 805 806
 * <br> Can be created by linphone_chat_room_create_message().
 */
typedef struct _LinphoneChatMessage LinphoneChatMessage;
Guillaume BIENKOWSKI's avatar
Guillaume BIENKOWSKI committed
807

jehan's avatar
jehan committed
808 809 810 811
/**
 * A chat room is the place where text messages are exchanged.
 * <br> Can be created by linphone_core_create_chat_room().
 */
aymeric's avatar
aymeric committed
812
typedef struct _LinphoneChatRoom LinphoneChatRoom;
jehan's avatar
jehan committed
813 814

/**
815
 * LinphoneChatMessageState is used to notify if messages have been succesfully delivered or not.
jehan's avatar
jehan committed
816
 */
817 818 819
typedef enum _LinphoneChatMessageState {
	LinphoneChatMessageStateIdle, /**< Initial state */
	LinphoneChatMessageStateInProgress, /**< Delivery in progress */
820
	LinphoneChatMessageStateDelivered, /**< Message successfully delivered and acknowledged by remote end point */
821
	LinphoneChatMessageStateNotDelivered, /**< Message was not delivered */
822 823
	LinphoneChatMessageStateFileTransferError, /**< Message was received(and acknowledged) but cannot get file from server */
	LinphoneChatMessageStateFileTransferDone /**< File transfer has been completed successfully. */
824
} LinphoneChatMessageState;
jehan's avatar
jehan committed
825

826 827 828 829 830 831
typedef enum _LinphoneLimeState {
	LinphoneLimeDisabled, /**< Lime is not used at all */
	LinphoneLimeMandatory, /**< Lime is always used */
	LinphoneLimePreferred, /**< Lime is used only if we already shared a secret with remote */
} LinphoneLimeState;

jehan's avatar
jehan committed
832
/**
Simon Morlat's avatar
Simon Morlat committed
833
 * Call back used to notify message delivery status
834 835 836 837
 * @param msg #LinphoneChatMessage object
 * @param status LinphoneChatMessageState
 * @param ud application user data
 * @deprecated
jehan's avatar
jehan committed
838
 */
839
typedef void (*LinphoneChatMessageStateChangedCb)(LinphoneChatMessage* msg,LinphoneChatMessageState state,void* ud);
840

841 842 843 844 845
/**
 * Call back used to notify message delivery status
 * @param msg #LinphoneChatMessage object
 * @param status LinphoneChatMessageState
 */
846
typedef void (*LinphoneChatMessageCbsMsgStateChangedCb)(LinphoneChatMessage* msg, LinphoneChatMessageState state);
847 848 849 850 851

/**
 * File transfer receive callback prototype. This function is called by the core upon an incoming File transfer is started. This function may be call several time for the same file in case of large file.
 * @param message #LinphoneChatMessage message from which the body is received.
 * @param content #LinphoneContent incoming content information
852
 * @param buffer #LinphoneBuffer holding the received data. Empty buffer means end of file.
853
 */
854
typedef void (*LinphoneChatMessageCbsFileTransferRecvCb)(LinphoneChatMessage *message, const LinphoneContent* content, const LinphoneBuffer *buffer);
855 856

/**
857
 * File transfer send callback prototype. This function is called by the core when an outgoing file transfer is started. This function is called until size is set to 0.
858 859
 * @param message #LinphoneChatMessage message from which the body is received.
 * @param content #LinphoneContent outgoing content
860 861 862
 * @param offset the offset in the file from where to get the data to be sent
 * @param size the number of bytes expected by the framework
 * @return A LinphoneBuffer object holding the data written by the application. An empty buffer means end of file.
863
 */
864
typedef LinphoneBuffer * (*LinphoneChatMessageCbsFileTransferSendCb)(LinphoneChatMessage *message,  const LinphoneContent* content, size_t offset, size_t size);
865 866 867 868 869 870 871 872

/**
 * File transfer progress indication callback prototype.
 * @param message #LinphoneChatMessage message from which the body is received.
 * @param content #LinphoneContent incoming content information
 * @param offset The number of bytes sent/received since the beginning of the transfer.
 * @param total The total number of bytes to be sent/received.
 */
873
typedef void (*LinphoneChatMessageCbsFileTransferProgressIndicationCb)(LinphoneChatMessage *message, const LinphoneContent* content, size_t offset, size_t total);
874

875 876 877 878 879 880 881
/**
 * Sets the database filename where chat messages will be stored.
 * If the file does not exist, it will be created.
 * @param[in] lc LinphoneCore object
 * @param[in] path The filesystem path to the database to stare the chat messages
 * @ingroup initializing
**/
Ghislain MARY's avatar
Ghislain MARY committed
882
LINPHONE_PUBLIC void linphone_core_set_chat_database_path(LinphoneCore *lc, const char *path);
Simon Morlat's avatar
Simon Morlat committed
883

jehan's avatar
jehan committed
884 885 886 887 888
/**
 * Get path to the database file used for storing chat messages.
 * @param lc the linphone core
 * @return file path or NULL if not exist
 **/
889

jehan's avatar
jehan committed
890
LINPHONE_PUBLIC const char *linphone_core_get_chat_database_path(const LinphoneCore *lc);
891 892
/**
 * Get a chat room whose peer is the supplied address. If it does not exist yet, it will be created.
Simon Morlat's avatar
Simon Morlat committed
893
 * No reference is transfered to the application. The LinphoneCore keeps a reference on the chat room.
894 895 896 897
 * @param lc the linphone core
 * @param addr a linphone address.
 * @return #LinphoneChatRoom where messaging can take place.
**/
898
LINPHONE_PUBLIC LinphoneChatRoom *linphone_core_get_chat_room(LinphoneCore *lc, const LinphoneAddress *addr);
899 900
/**
 * Get a chat room for messaging from a sip uri like sip:joe@sip.linphone.org. If it does not exist yet, it will be created.
Simon Morlat's avatar
Simon Morlat committed
901
 * No reference is transfered to the application. The LinphoneCore keeps a reference on the chat room.
Ghislain MARY's avatar
Ghislain MARY committed
902
 * @param lc A #LinphoneCore object
903 904 905
 * @param to The destination address for messages.
 * @return #LinphoneChatRoom where messaging can take place.
**/
906
LINPHONE_PUBLIC LinphoneChatRoom *linphone_core_get_chat_room_from_uri(LinphoneCore *lc, const char *to);
Simon Morlat's avatar
Simon Morlat committed
907 908 909

/**
 * Removes a chatroom including all message history from the LinphoneCore.
Ghislain MARY's avatar
Ghislain MARY committed
910 911
 * @param lc A #LinphoneCore object
 * @param cr A #LinphoneChatRoom object
Simon Morlat's avatar
Simon Morlat committed
912 913 914
**/
LINPHONE_PUBLIC void linphone_core_delete_chat_room(LinphoneCore *lc, LinphoneChatRoom *cr);

915 916
/**
 * Inconditionnaly disable incoming chat messages.
Ghislain MARY's avatar
Ghislain MARY committed
917
 * @param lc A #LinphoneCore object
918 919
 * @param deny_reason the deny reason (#LinphoneReasonNone has no effect).
**/
Simon Morlat's avatar
Simon Morlat committed
920
LINPHONE_PUBLIC void linphone_core_disable_chat(LinphoneCore *lc, LinphoneReason deny_reason);
921 922 923
/**
 * Enable reception of incoming chat messages.
 * By default it is enabled but it can be disabled with linphone_core_disable_chat().
Ghislain MARY's avatar
Ghislain MARY committed
924
 * @param lc A #LinphoneCore object
925
**/
Simon Morlat's avatar
Simon Morlat committed
926
LINPHONE_PUBLIC void linphone_core_enable_chat(LinphoneCore *lc);
927 928
/**
 * Returns whether chat is enabled.
Ghislain MARY's avatar
Ghislain MARY committed
929
 * @param lc A #LinphoneCore object
930
**/
Simon Morlat's avatar
Simon Morlat committed
931
LINPHONE_PUBLIC bool_t linphone_core_chat_enabled(const LinphoneCore *lc);
932 933 934 935 936
/**
 * Destroy a LinphoneChatRoom.
 * @param cr #LinphoneChatRoom object
 * @deprecated Use linphone_chat_room_unref() instead.
 */
Ghislain MARY's avatar
Ghislain MARY committed
937
LINPHONE_PUBLIC LINPHONE_DEPRECATED void linphone_chat_room_destroy(LinphoneChatRoom *cr);
938 939 940 941 942 943
/**
 * Create a message attached to a dedicated chat room;
 * @param cr the chat room.
 * @param message text message, NULL if absent.
 * @return a new #LinphoneChatMessage
 */
944
LINPHONE_PUBLIC LinphoneChatMessage* linphone_chat_room_create_message(LinphoneChatRoom *cr,const char* message);
945 946 947 948 949 950 951 952 953 954 955
/**
 * Create a message attached to a dedicated chat room;
 * @param cr the chat room.
 * @param message text message, NULL if absent.
 * @param external_body_url the URL given in external body or NULL.
 * @param state the LinphoneChatMessage.State of the message.
 * @param time the time_t at which the message has been received/sent.
 * @param is_read TRUE if the message should be flagged as read, FALSE otherwise.
 * @param is_incoming TRUE if the message has been received, FALSE otherwise.
 * @return a new #LinphoneChatMessage
 */
956
LINPHONE_PUBLIC LinphoneChatMessage* linphone_chat_room_create_message_2(LinphoneChatRoom *cr, const char* message, const char* external_body_url, LinphoneChatMessageState state, time_t time, bool_t is_read, bool_t is_incoming);
jehan's avatar
jehan committed
957

958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984
/**
 * Acquire a reference to the chat room.
 * @param[in] cr The chat room.
 * @return The same chat room.
**/
LINPHONE_PUBLIC LinphoneChatRoom *linphone_chat_room_ref(LinphoneChatRoom *cr);

/**
 * Release reference to the chat room.
 * @param[in] cr The chat room.
**/
LINPHONE_PUBLIC void linphone_chat_room_unref(LinphoneChatRoom *cr);

/**
 * Retrieve the user pointer associated with the chat room.
 * @param[in] cr The chat room.
 * @return The user pointer associated with the chat room.
**/
LINPHONE_PUBLIC void *linphone_chat_room_get_user_data(const LinphoneChatRoom *cr);

/**
 * Assign a user pointer to the chat room.
 * @param[in] cr The chat room.
 * @param[in] ud The user pointer to associate with the chat room.
**/
LINPHONE_PUBLIC void linphone_chat_room_set_user_data(LinphoneChatRoom *cr, void *ud);

985 986
 /**
 * Create a message attached to a dedicated chat room with a particular content.
987
 * Use #linphone_chat_room_send_message to initiate the transfer
988 989
 * @param cr the chat room.
 * @param initial_content #LinphoneContent initial content. #LinphoneCoreVTable.file_transfer_send is invoked later to notify file transfer progress and collect next chunk of the message if #LinphoneContent.data is NULL.
jehan's avatar
jehan committed
990 991
 * @return a new #LinphoneChatMessage
 */
992
LINPHONE_PUBLIC LinphoneChatMessage* linphone_chat_room_create_file_transfer_message(LinphoneChatRoom *cr, const LinphoneContent* initial_content);
jehan's avatar
jehan committed
993

994 995 996 997 998
/**
 * get peer address \link linphone_core_get_chat_room() associated to \endlink this #LinphoneChatRoom
 * @param cr #LinphoneChatRoom object
 * @return #LinphoneAddress peer address
 */
999
LINPHONE_PUBLIC const LinphoneAddress* linphone_chat_room_get_peer_address(LinphoneChatRoom *cr);
1000

1001 1002
/**
 * Send a message to peer member of this chat room.
1003
 * @deprecated Use linphone_chat_room_send_chat_message() instead.
1004 1005 1006
 * @param cr #LinphoneChatRoom object
 * @param msg message to be sent
 */
1007
LINPHONE_PUBLIC LINPHONE_DEPRECATED void linphone_chat_room_send_message(LinphoneChatRoom *cr, const char *msg);
1008 1009 1010 1011 1012 1013 1014 1015
/**
 * Send a message to peer member of this chat room.
 * @param cr #LinphoneChatRoom object
 * @param msg #LinphoneChatMessage message to be sent
 * @param status_cb LinphoneChatMessageStateChangeCb status callback invoked when message is delivered or could not be delivered. May be NULL
 * @param ud user data for the status cb.
 * @deprecated Use linphone_chat_room_send_chat_message() instead.
 * @note The LinphoneChatMessage must not be destroyed until the the callback is called.
Simon Morlat's avatar
Simon Morlat committed
1016
 * The LinphoneChatMessage reference is transfered to the function and thus doesn't need to be unref'd by the application.