linphonecore.h 180 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 17 18 19 20 21 22 23 24

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 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"
26
#include "mediastreamer2/mediastream.h"
27
#include "mediastreamer2/bitratecontrol.h"
28 29

#ifdef IN_LINPHONE
smorlat's avatar
smorlat committed
30
#include "sipsetup.h"
31 32 33
#else
#include "linphone/sipsetup.h"
#endif
aymeric's avatar
aymeric committed
34

Ghislain MARY's avatar
Ghislain MARY committed
35 36
#include "lpconfig.h"

smorlat's avatar
smorlat committed
37
#define LINPHONE_IPADDR_SIZE 64
smorlat's avatar
smorlat committed
38
#define LINPHONE_HOSTNAME_SIZE 128
smorlat's avatar
smorlat committed
39

jehan's avatar
jehan committed
40 41
#ifndef LINPHONE_PUBLIC
	#define LINPHONE_PUBLIC MS2_PUBLIC
42 43
#endif

44
#ifndef LINPHONE_DEPRECATED
45 46 47 48 49 50
#if defined(_MSC_VER)
	#define LINPHONE_DEPRECATED __declspec(deprecated)
#else
	#define LINPHONE_DEPRECATED __attribute__ ((deprecated))
#endif
#endif
51 52


aymeric's avatar
aymeric committed
53 54 55 56 57
#ifdef __cplusplus
extern "C" {
#endif

struct _LinphoneCore;
58
struct _LinphoneChatRoom;
59 60 61
struct _LinphoneAuthInfo;
struct _SipSetupContext;
struct _LinphoneInfoMessage;
62

63 64 65 66 67
/**
 * Linphone core main object created by function linphone_core_new() .
 * @ingroup initializing
 */
typedef struct _LinphoneCore LinphoneCore;
aymeric's avatar
aymeric committed
68

69

70 71 72 73 74 75 76 77 78 79 80 81 82
/**
 * 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
 */
#define LC_SIP_TRANSPORT_RANDOM -1

jehan's avatar
jehan committed
83 84 85 86 87
/**
 * Linphone core SIP transport ports.
 * Use with #linphone_core_set_sip_transports
 * @ingroup initializing
 */
88
typedef struct _LCSipTransports{
jehan's avatar
jehan committed
89 90 91
	/**
	 * udp port to listening on, negative value if not set
	 * */
92
	int udp_port;
jehan's avatar
jehan committed
93 94 95
	/**
	 * tcp port to listening on, negative value if not set
	 * */
96
	int tcp_port;
jehan's avatar
jehan committed
97 98 99
	/**
	 * dtls port to listening on, negative value if not set
	 * */
100
	int dtls_port;
jehan's avatar
jehan committed
101 102 103
	/**
	 * tls port to listening on, negative value if not set
	 * */
104
	int tls_port;
105 106
} LCSipTransports;

107

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

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

126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141
/**
 * 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;
142 143 144 145 146 147 148

/**
 * Internal object of LinphoneCore representing a conference
 * @ingroup call_control
 */
typedef struct _LinphoneConference LinphoneConference;

149
/**
150
 * Function returning a human readable value for LinphoneStreamType.
151 152
 * @ingroup initializing
 **/
153

154
LINPHONE_PUBLIC const char *linphone_stream_type_to_string(const LinphoneStreamType);
smorlat's avatar
smorlat committed
155 156 157 158 159 160 161 162 163 164
/**
 * Object that represents a SIP address.
 *
 * The LinphoneAddress is an opaque object to represents SIP addresses, ie
 * the content of SIP's 'from' and 'to' headers.
 * A SIP address is made of display name, username, domain name, port, and various
 * uri headers (such as tags). It looks like 'Alice <sip:alice@example.net>'.
 * The LinphoneAddress has methods to extract and manipulate all parts of the address.
 * When some part of the address (for example the username) is empty, the accessor methods
 * return NULL.
165
 *
smorlat's avatar
smorlat committed
166 167
 * @ingroup linphone_address
 */
168
typedef struct SalAddress LinphoneAddress;
169

170 171
typedef struct belle_sip_dict LinphoneDictionary;

172 173 174 175 176 177 178 179 180 181 182
/**
 * The LinphoneCall object represents a call issued or received by the LinphoneCore
 * @ingroup call_control
**/
struct _LinphoneCall;
/**
 * The LinphoneCall object represents a call issued or received by the LinphoneCore
 * @ingroup call_control
**/
typedef struct _LinphoneCall LinphoneCall;

183
/**
184 185 186
 * Enum describing various failure reasons or contextual information for some events.
 * @see linphone_call_get_reason()
 * @see linphone_proxy_config_get_error()
187
 * @see linphone_error_info_get_reason()
188 189 190 191 192
 * @ingroup misc
**/
enum _LinphoneReason{
	LinphoneReasonNone,
	LinphoneReasonNoResponse, /**<No response received from remote*/
193
	LinphoneReasonForbidden, /**<Authentication failed due to bad credentials or resource forbidden*/
194
	LinphoneReasonDeclined, /**<The call has been declined*/
195 196
	LinphoneReasonNotFound, /**<Destination of the call was not found.*/
	LinphoneReasonNotAnswered, /**<The call was not answered in time (request timeout)*/
197
	LinphoneReasonBusy, /**<Phone line was busy */
198
	LinphoneReasonUnsupportedContent, /**<Unsupported content */
jehan's avatar
jehan committed
199
	LinphoneReasonIOError, /**<Transport error: connection failures, disconnections etc...*/
jehan's avatar
jehan committed
200
	LinphoneReasonDoNotDisturb, /**<Do not disturb reason*/
201
	LinphoneReasonUnauthorized, /**<Operation is unauthorized because missing credential*/
202
	LinphoneReasonNotAcceptable, /**<Operation like call update rejected by peer*/
203 204
	LinphoneReasonNoMatch, /**<Operation could not be executed by server or remote client because it didn't have any context for it*/
	LinphoneReasonMovedPermanently, /**<Resource moved permanently*/
205
	LinphoneReasonGone, /**<Resource no longer exists*/
206 207 208 209
	LinphoneReasonTemporarilyUnavailable, /**<Temporarily unavailable*/
	LinphoneReasonAddressIncomplete, /**<Address incomplete*/
	LinphoneReasonNotImplemented, /**<Not implemented*/
	LinphoneReasonBadGateway, /**<Bad gateway*/
210 211
	LinphoneReasonServerTimeout, /**<Server timeout*/
	LinphoneReasonUnknown /**Unknown reason*/
212 213
};

214 215
#define LinphoneReasonBadCredentials LinphoneReasonForbidden

216 217 218
/*for compatibility*/
#define LinphoneReasonMedia LinphoneReasonUnsupportedContent

219 220 221 222 223 224 225 226 227 228
/**
 * Enum describing failure reasons.
 * @ingroup misc
**/
typedef enum _LinphoneReason LinphoneReason;

/**
 * Converts a LinphoneReason enum to a string.
 * @ingroup misc
**/
229
LINPHONE_PUBLIC const char *linphone_reason_to_string(LinphoneReason err);
230

231 232 233 234 235 236 237 238 239 240 241 242
/**
 * Object representing full details about a signaling error or status.
 * All LinphoneErrorInfo object returned by the liblinphone API are readonly and transcients. For safety they must be used immediately
 * after obtaining them. Any other function call to the liblinphone may change their content or invalidate the pointer.
 * @ingroup misc
**/
typedef struct _LinphoneErrorInfo LinphoneErrorInfo;

LINPHONE_PUBLIC LinphoneReason linphone_error_info_get_reason(const LinphoneErrorInfo *ei);
LINPHONE_PUBLIC const char *linphone_error_info_get_phrase(const LinphoneErrorInfo *ei);
LINPHONE_PUBLIC const char *linphone_error_info_get_details(const LinphoneErrorInfo *ei);
LINPHONE_PUBLIC int linphone_error_info_get_protocol_code(const LinphoneErrorInfo *ei);
243 244

/* linphone dictionary */
245
LINPHONE_PUBLIC	LinphoneDictionary* linphone_dictionary_new(void);
246 247 248
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);
249 250 251 252 253 254 255 256
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);
257
LINPHONE_PUBLIC int linphone_dictionary_haskey(const LinphoneDictionary* obj, const char* key);
258 259 260 261 262 263
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
 */
264
LINPHONE_PUBLIC LinphoneDictionary* lp_config_section_to_dict( const LpConfig* lpconfig, const char* section );
265 266 267 268 269 270

/**
 * 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
 */
271
LINPHONE_PUBLIC void lp_config_load_dict_to_section( LpConfig* lpconfig, const char* section, const LinphoneDictionary* dict);
272 273


274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302
/**
 * @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.
 */
303
LINPHONE_PUBLIC const char * linphone_payload_type_get_mime_type(const LinphonePayloadType *pt);
304 305 306 307 308 309 310 311

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

312

313 314 315 316 317 318 319 320 321 322 323 324 325 326
/**
 * 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;

327 328 329 330 331 332
/**
 * 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
333 334
	LinphoneMediaEncryptionZRTP, /**< Use ZRTP media encryption */
	LinphoneMediaEncryptionDTLS /**< Use DTLS media encryption */
335 336 337 338 339 340 341 342 343 344 345 346
};

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

347 348 349 350
/**
 * @}
**/

351

Simon Morlat's avatar
Simon Morlat committed
352 353 354
/*
 * Note for developers: this enum must be kept synchronized with the SalPrivacy enum declared in sal.h
 */
Simon Morlat's avatar
Simon Morlat committed
355
/**
jehan's avatar
jehan committed
356
 * @ingroup call_control
357
 * Defines privacy policy to apply as described by rfc3323
Simon Morlat's avatar
Simon Morlat committed
358
**/
jehan's avatar
jehan committed
359 360
typedef enum _LinphonePrivacy {
	/**
Simon Morlat's avatar
Simon Morlat committed
361
	 * Privacy services must not perform any privacy function
jehan's avatar
jehan committed
362
	 */
Simon Morlat's avatar
Simon Morlat committed
363
	LinphonePrivacyNone=0x0,
jehan's avatar
jehan committed
364
	/**
365
	 * Request that privacy services provide a user-level privacy
Simon Morlat's avatar
Simon Morlat committed
366 367
	 * function.
	 * With this mode, "from" header is hidden, usually replaced by  From: "Anonymous" <sip:anonymous@anonymous.invalid>
jehan's avatar
jehan committed
368
	 */
369
	LinphonePrivacyUser=0x1,
jehan's avatar
jehan committed
370
	/**
371
	 * Request that privacy services modify headers that cannot
Simon Morlat's avatar
Simon Morlat committed
372
	 * be set arbitrarily by the user (Contact/Via).
jehan's avatar
jehan committed
373
	 */
374
	LinphonePrivacyHeader=0x2,
Simon Morlat's avatar
Simon Morlat committed
375
	/**
376
	 *  Request that privacy services provide privacy for session
Simon Morlat's avatar
Simon Morlat committed
377 378
	 * media
	 */
379 380 381 382
	LinphonePrivacySession=0x4,
	/**
	 * rfc3325
	 * The presence of this privacy type in
Simon Morlat's avatar
Simon Morlat committed
383 384 385 386 387
	 * 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
388 389 390 391 392
	 *
	 */
	LinphonePrivacyId=0x8,
	/**
	 * Privacy service must perform the specified services or
Simon Morlat's avatar
Simon Morlat committed
393
	 * fail the request
394 395
	 *
	 **/
Simon Morlat's avatar
Simon Morlat committed
396
	LinphonePrivacyCritical=0x10,
397

Simon Morlat's avatar
Simon Morlat committed
398
	/**
Simon Morlat's avatar
Simon Morlat committed
399
	 * 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
400 401
	 */
	LinphonePrivacyDefault=0x8000,
jehan's avatar
jehan committed
402
} LinphonePrivacy;
403 404 405 406 407
/*
 * a mask  of #LinphonePrivacy values
 * */
typedef unsigned int LinphonePrivacyMask;

408 409

LINPHONE_PUBLIC const char* linphone_privacy_to_string(LinphonePrivacy privacy);
410 411 412


#ifdef IN_LINPHONE
413
#include "buffer.h"
414 415
#include "call_log.h"
#include "call_params.h"
416 417 418
#include "content.h"
#include "event.h"
#include "linphonefriend.h"
419
#include "xmlrpc.h"
420
#include "carddav.h"
421
#else
422
#include "linphone/buffer.h"
423 424
#include "linphone/call_log.h"
#include "linphone/call_params.h"
425 426 427
#include "linphone/content.h"
#include "linphone/event.h"
#include "linphone/linphonefriend.h"
428
#include "linphone/xmlrpc.h"
429
#include "linphone/carddav.h"
430 431 432 433 434 435 436 437 438 439 440
#endif

LINPHONE_PUBLIC	LinphoneAddress * linphone_address_new(const char *addr);
LINPHONE_PUBLIC LinphoneAddress * linphone_address_clone(const LinphoneAddress *addr);
LINPHONE_PUBLIC LinphoneAddress * linphone_address_ref(LinphoneAddress *addr);
LINPHONE_PUBLIC void linphone_address_unref(LinphoneAddress *addr);
LINPHONE_PUBLIC const char *linphone_address_get_scheme(const LinphoneAddress *u);
LINPHONE_PUBLIC	const char *linphone_address_get_display_name(const LinphoneAddress* u);
LINPHONE_PUBLIC	const char *linphone_address_get_username(const LinphoneAddress *u);
LINPHONE_PUBLIC	const char *linphone_address_get_domain(const LinphoneAddress *u);
LINPHONE_PUBLIC int linphone_address_get_port(const LinphoneAddress *u);
441 442 443 444 445
LINPHONE_PUBLIC	int linphone_address_set_display_name(LinphoneAddress *u, const char *display_name);
LINPHONE_PUBLIC	int linphone_address_set_username(LinphoneAddress *uri, const char *username);
LINPHONE_PUBLIC	int linphone_address_set_domain(LinphoneAddress *uri, const char *host);
LINPHONE_PUBLIC	int linphone_address_set_port(LinphoneAddress *uri, int port);
LINPHONE_PUBLIC int linphone_address_set_transport(LinphoneAddress *uri,LinphoneTransportType type);
446 447
/*remove tags, params etc... so that it is displayable to the user*/
LINPHONE_PUBLIC	void linphone_address_clean(LinphoneAddress *uri);
448 449 450
LINPHONE_PUBLIC bool_t linphone_address_is_secure(const LinphoneAddress *addr);
LINPHONE_PUBLIC bool_t linphone_address_get_secure(const LinphoneAddress *addr);
LINPHONE_PUBLIC void linphone_address_set_secure(LinphoneAddress *addr, bool_t enabled);
451
LINPHONE_PUBLIC bool_t linphone_address_is_sip(const LinphoneAddress *uri);
452
LINPHONE_PUBLIC LinphoneTransportType linphone_address_get_transport(const LinphoneAddress *uri);
453 454
LINPHONE_PUBLIC const char *linphone_address_get_method_param(const LinphoneAddress *addr);
LINPHONE_PUBLIC void linphone_address_set_method_param(LinphoneAddress *addr, const char *method);
455 456 457
LINPHONE_PUBLIC	char *linphone_address_as_string(const LinphoneAddress *u);
LINPHONE_PUBLIC	char *linphone_address_as_string_uri_only(const LinphoneAddress *u);
LINPHONE_PUBLIC	bool_t linphone_address_weak_equal(const LinphoneAddress *a1, const LinphoneAddress *a2);
458
LINPHONE_PUBLIC bool_t linphone_address_equal(const LinphoneAddress *a1, const LinphoneAddress *a2);
459 460 461
LINPHONE_PUBLIC void linphone_address_set_password(LinphoneAddress *addr, const char *passwd);
LINPHONE_PUBLIC const char *linphone_address_get_password(const LinphoneAddress *addr);
LINPHONE_PUBLIC void linphone_address_set_header(LinphoneAddress *addr, const char *header_name, const char *header_value);
462 463 464 465 466 467 468 469 470 471 472
LINPHONE_PUBLIC	void linphone_address_destroy(LinphoneAddress *u);

/**
 * 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
473 474 475 476 477
/**
 * The LinphoneInfoMessage is an object representing an informational message sent or received by the core.
**/
typedef struct _LinphoneInfoMessage LinphoneInfoMessage;

478 479
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
480
LINPHONE_PUBLIC void linphone_info_message_add_header(LinphoneInfoMessage *im, const char *name, const char *value);
Simon Morlat's avatar
Simon Morlat committed
481
LINPHONE_PUBLIC const char *linphone_info_message_get_header(const LinphoneInfoMessage *im, const char *name);
Simon Morlat's avatar
Simon Morlat committed
482
LINPHONE_PUBLIC void linphone_info_message_set_content(LinphoneInfoMessage *im,  const LinphoneContent *content);
Simon Morlat's avatar
Simon Morlat committed
483
LINPHONE_PUBLIC const LinphoneContent * linphone_info_message_get_content(const LinphoneInfoMessage *im);
Simon Morlat's avatar
Simon Morlat committed
484
LINPHONE_PUBLIC void linphone_info_message_destroy(LinphoneInfoMessage *im);
485
LINPHONE_PUBLIC LinphoneInfoMessage *linphone_info_message_copy(const LinphoneInfoMessage *orig);
Simon Morlat's avatar
Simon Morlat committed
486

487 488


489 490
/**
 * Structure describing policy regarding video streams establishments.
Simon Morlat's avatar
Simon Morlat committed
491
 * @ingroup media_parameters
492 493
**/
struct _LinphoneVideoPolicy{
494
	bool_t automatically_initiate; /**<Whether video shall be automatically proposed for outgoing calls.*/
495 496 497 498
	bool_t automatically_accept; /**<Whether video shall be automatically accepted for incoming calls*/
	bool_t unused[2];
};

Simon Morlat's avatar
Simon Morlat committed
499 500 501 502
/**
 * Structure describing policy regarding video streams establishments.
 * @ingroup media_parameters
**/
503 504
typedef struct _LinphoneVideoPolicy LinphoneVideoPolicy;

505

506 507


Simon Morlat's avatar
Simon Morlat committed
508 509 510 511 512
/**
 * @addtogroup call_misc
 * @{
**/

513 514 515
#define LINPHONE_CALL_STATS_AUDIO ((int)LinphoneStreamTypeAudio)
#define LINPHONE_CALL_STATS_VIDEO ((int)LinphoneStreamTypeVideo)
#define LINPHONE_CALL_STATS_TEXT  ((int)LinphoneStreamTypeText)
516

517 518 519 520 521
/**
 * Enum describing ICE states.
 * @ingroup initializing
**/
enum _LinphoneIceState{
Simon Morlat's avatar
Simon Morlat committed
522
	LinphoneIceStateNotActivated, /**< ICE has not been activated for this call or stream*/
Ghislain MARY's avatar
Ghislain MARY committed
523
	LinphoneIceStateFailed, /**< ICE processing has failed */
524 525 526 527 528 529 530 531 532 533 534 535
	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;

536 537
LINPHONE_PUBLIC const char *linphone_ice_state_to_string(LinphoneIceState state);

Yann Diorcet's avatar
Yann Diorcet committed
538 539 540 541 542 543 544 545 546 547 548 549
/**
 * 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 */
550
	LinphoneUpnpStateBlacklisted, /**< IGD router is blacklisted */
Yann Diorcet's avatar
Yann Diorcet committed
551 552 553 554 555 556 557 558
};

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

559

560 561
#define LINPHONE_CALL_STATS_RECEIVED_RTCP_UPDATE (1 << 0) /**< received_rtcp field of LinphoneCallStats object has been updated */
#define LINPHONE_CALL_STATS_SENT_RTCP_UPDATE (1 << 1) /**< sent_rtcp field of LinphoneCallStats object has been updated */
562
#define LINPHONE_CALL_STATS_PERIODICAL_UPDATE (1 << 2) /**< Every seconds LinphoneCallStats object has been updated */
563

Simon Morlat's avatar
Simon Morlat committed
564 565 566
/**
 * The LinphoneCallStats objects carries various statistic informations regarding quality of audio or video streams.
 *
567
 * To receive these informations periodically and as soon as they are computed, the application is invited to place a #LinphoneCoreCallStatsUpdatedCb callback in the LinphoneCoreVTable structure
Simon Morlat's avatar
Simon Morlat committed
568 569 570 571 572 573 574 575 576
 * it passes for instanciating the LinphoneCore object (see linphone_core_new() ).
 *
 * At any time, the application can access last computed statistics using linphone_call_get_audio_stats() or linphone_call_get_video_stats().
**/
typedef struct _LinphoneCallStats LinphoneCallStats;

/**
 * The LinphoneCallStats objects carries various statistic informations regarding quality of audio or video streams.
 *
577
 * To receive these informations periodically and as soon as they are computed, the application is invited to place a #LinphoneCoreCallStatsUpdatedCb callback in the LinphoneCoreVTable structure
578
 * it passes for instantiating the LinphoneCore object (see linphone_core_new() ).
Simon Morlat's avatar
Simon Morlat committed
579 580 581 582 583 584 585 586 587
 *
 * At any time, the application can access last computed statistics using linphone_call_get_audio_stats() or linphone_call_get_video_stats().
**/
struct _LinphoneCallStats {
	int		type; /**< Can be either LINPHONE_CALL_STATS_AUDIO or LINPHONE_CALL_STATS_VIDEO*/
	jitter_stats_t	jitter_stats; /**<jitter buffer statistics, see oRTP documentation for details */
	mblk_t*		received_rtcp; /**<Last RTCP packet received, as a mblk_t structure. See oRTP documentation for details how to extract information from it*/
	mblk_t*		sent_rtcp;/**<Last RTCP packet sent, as a mblk_t structure. See oRTP documentation for details how to extract information from it*/
	float		round_trip_delay; /**<Round trip propagation time in seconds if known, -1 if unknown.*/
588
	LinphoneIceState	ice_state; /**< State of ICE processing. */
Yann Diorcet's avatar
Yann Diorcet committed
589
	LinphoneUpnpState	upnp_state; /**< State of uPnP processing. */
590 591
	float download_bandwidth; /**<Download bandwidth measurement of received stream, expressed in kbit/s, including IP/UDP/RTP headers*/
	float upload_bandwidth; /**<Download bandwidth measurement of sent stream, expressed in kbit/s, including IP/UDP/RTP headers*/
592 593
	float local_late_rate; /**<percentage of packet received too late over last second*/
	float local_loss_rate; /**<percentage of lost packet over last second*/
594
	int updated; /**< Tell which RTCP packet has been updated (received_rtcp or sent_rtcp). Can be either LINPHONE_CALL_STATS_RECEIVED_RTCP_UPDATE or LINPHONE_CALL_STATS_SENT_RTCP_UPDATE */
595 596
	float rtcp_download_bandwidth; /**<RTCP download bandwidth measurement of received stream, expressed in kbit/s, including IP/UDP/RTP headers*/
	float rtcp_upload_bandwidth; /**<RTCP download bandwidth measurement of sent stream, expressed in kbit/s, including IP/UDP/RTP headers*/
597
	rtp_stats_t rtp_stats; /**< RTP stats */
598
	bool_t rtcp_received_via_mux; /*private flag, for non-regression test only*/
Simon Morlat's avatar
Simon Morlat committed
599 600 601 602 603
};

/**
 * @}
**/
604

Sylvain Berfini's avatar
Sylvain Berfini committed
605 606
LINPHONE_PUBLIC const LinphoneCallStats *linphone_call_get_audio_stats(LinphoneCall *call);
LINPHONE_PUBLIC const LinphoneCallStats *linphone_call_get_video_stats(LinphoneCall *call);
607
LINPHONE_PUBLIC const LinphoneCallStats *linphone_call_get_text_stats(LinphoneCall *call);
608 609 610 611
LINPHONE_PUBLIC float linphone_call_stats_get_sender_loss_rate(const LinphoneCallStats *stats);
LINPHONE_PUBLIC float linphone_call_stats_get_receiver_loss_rate(const LinphoneCallStats *stats);
LINPHONE_PUBLIC float linphone_call_stats_get_sender_interarrival_jitter(const LinphoneCallStats *stats, LinphoneCall *call);
LINPHONE_PUBLIC float linphone_call_stats_get_receiver_interarrival_jitter(const LinphoneCallStats *stats, LinphoneCall *call);
612
LINPHONE_PUBLIC rtp_stats_t linphone_call_stats_get_rtp_stats(const LinphoneCallStats *statss);
613
LINPHONE_PUBLIC uint64_t linphone_call_stats_get_late_packets_cumulative_number(const LinphoneCallStats *stats, LinphoneCall *call);
614 615 616 617
LINPHONE_PUBLIC float linphone_call_stats_get_download_bandwidth(const LinphoneCallStats *stats);
LINPHONE_PUBLIC float linphone_call_stats_get_upload_bandwidth(const LinphoneCallStats *stats);
LINPHONE_PUBLIC LinphoneIceState linphone_call_stats_get_ice_state(const LinphoneCallStats *stats);
LINPHONE_PUBLIC LinphoneUpnpState linphone_call_stats_get_upnp_state(const LinphoneCallStats *stats);
618

619
/** Callback prototype */
620
typedef void (*LinphoneCallCbFunc)(LinphoneCall *call,void * user_data);
621

622 623 624 625 626 627 628 629 630 631 632 633 634 635
/**
 * 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);

636 637 638 639 640 641 642 643 644
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);
645

646
/**
647
 * Create an independent media file player.
648
 * This player support WAVE and MATROSKA formats.
649
 * @param lc A LinphoneCore object
650 651
 * @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
652
 * @param window_id Id of the drawing window. Depend of video out
653 654
 * @return A pointer on the new instance. NULL if faild.
 */
655
LINPHONE_PUBLIC LinphonePlayer *linphone_core_create_local_player(LinphoneCore *lc, MSSndCard *snd_card, const char *video_out, void *window_id);
656

657
/**
658
 * Check whether Matroksa format is supported by the player
659 660
 * @return TRUE if it is supported
 */
661
LINPHONE_PUBLIC bool_t linphone_local_player_matroska_supported(void);
662

Simon Morlat's avatar
Simon Morlat committed
663 664 665 666 667
/**
 * LinphoneCallState enum represents the different state a call can reach into.
 * The application is notified of state changes through the LinphoneCoreVTable::call_state_changed callback.
 * @ingroup call_control
**/
668
typedef enum _LinphoneCallState{
Simon Morlat's avatar
Simon Morlat committed
669
	LinphoneCallIdle,					/**<Initial call state */
670 671 672 673 674 675 676 677 678 679 680 681 682 683
	LinphoneCallIncomingReceived, /**<This is a new incoming call */
	LinphoneCallOutgoingInit, /**<An outgoing call is started */
	LinphoneCallOutgoingProgress, /**<An outgoing call is in progress */
	LinphoneCallOutgoingRinging, /**<An outgoing call is ringing at remote end */
	LinphoneCallOutgoingEarlyMedia, /**<An outgoing call is proposed early media */
	LinphoneCallConnected, /**<Connected, the call is answered */
	LinphoneCallStreamsRunning, /**<The media streams are established and running*/
	LinphoneCallPausing, /**<The call is pausing at the initiative of local end */
	LinphoneCallPaused, /**< The call is paused, remote end has accepted the pause */
	LinphoneCallResuming, /**<The call is being resumed by local end*/
	LinphoneCallRefered, /**<The call is being transfered to another party, resulting in a new outgoing call to follow immediately*/
	LinphoneCallError, /**<The call encountered an error*/
	LinphoneCallEnd, /**<The call ended normally*/
	LinphoneCallPausedByRemote, /**<The call is paused by remote end*/
Simon Morlat's avatar
Simon Morlat committed
684
	LinphoneCallUpdatedByRemote, /**<The call's parameters change is requested by remote end, used for example when video is added by remote */
685
	LinphoneCallIncomingEarlyMedia, /**<We are proposing early media to an incoming call */
686
	LinphoneCallUpdating, /**<A call update has been initiated by us */
687 688 689
	LinphoneCallReleased, /**< The call object is no more retained by the core */
	LinphoneCallEarlyUpdatedByRemote, /*<The call is updated by remote while not yet answered (early dialog SIP UPDATE received).*/
	LinphoneCallEarlyUpdating /*<We are updating the call while not yet answered (early dialog SIP UPDATE sent)*/
690 691
} LinphoneCallState;

692
LINPHONE_PUBLIC	const char *linphone_call_state_to_string(LinphoneCallState cs);
693

694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728
/**
 * Acquire a reference to the call.
 * An application that wishes to retain a pointer to call object
 * must use this function to unsure the pointer remains
 * valid. Once the application no more needs this pointer,
 * it must call linphone_call_unref().
 * @param[in] call The call.
 * @return The same call.
 * @ingroup call_control
**/
LINPHONE_PUBLIC LinphoneCall *linphone_call_ref(LinphoneCall *call);

/**
 * Release reference to the call.
 * @param[in] call The call.
 * @ingroup call_control
**/
LINPHONE_PUBLIC void linphone_call_unref(LinphoneCall *call);

/**
 * Retrieve the user pointer associated with the call.
 * @param[in] call The call.
 * @return The user pointer associated with the call.
 * @ingroup call_control
**/
LINPHONE_PUBLIC void *linphone_call_get_user_data(const LinphoneCall *call);

/**
 * Assign a user pointer to the call.
 * @param[in] cfg The call.
 * @param[in] ud The user pointer to associate with the call.
 * @ingroup call_control
**/
LINPHONE_PUBLIC void linphone_call_set_user_data(LinphoneCall *call, void *ud);

729 730 731 732 733 734
/**
 * Get the core that has created the specified call.
 * @param[in] call LinphoneCall object
 * @return The LinphoneCore object that has created the specified call.
 * @ingroup call_control
 */
735
LINPHONE_PUBLIC LinphoneCore *linphone_call_get_core(const LinphoneCall *call);
736

737
LINPHONE_PUBLIC	LinphoneCallState linphone_call_get_state(const LinphoneCall *call);
738
LINPHONE_PUBLIC bool_t linphone_call_asked_to_autoanswer(LinphoneCall *call);
739 740 741 742 743 744 745

/**
 * 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
 */
Simon Morlat's avatar
Simon Morlat committed
746
LINPHONE_PUBLIC	const LinphoneAddress * linphone_core_get_current_call_remote_address(LinphoneCore *lc);
747

Sylvain Berfini's avatar
Sylvain Berfini committed
748 749 750
LINPHONE_PUBLIC	const LinphoneAddress * linphone_call_get_remote_address(const LinphoneCall *call);
LINPHONE_PUBLIC	char *linphone_call_get_remote_address_as_string(const LinphoneCall *call);
LINPHONE_PUBLIC	LinphoneCallDir linphone_call_get_dir(const LinphoneCall *call);
751
LINPHONE_PUBLIC	LinphoneCallLog *linphone_call_get_call_log(const LinphoneCall *call);
752 753 754 755
LINPHONE_PUBLIC const char *linphone_call_get_refer_to(const LinphoneCall *call);
LINPHONE_PUBLIC bool_t linphone_call_has_transfer_pending(const LinphoneCall *call);
LINPHONE_PUBLIC LinphoneCall *linphone_call_get_transferer_call(const LinphoneCall *call);
LINPHONE_PUBLIC LinphoneCall *linphone_call_get_transfer_target_call(const LinphoneCall *call);
756
LINPHONE_PUBLIC	LinphoneCall *linphone_call_get_replaced_call(LinphoneCall *call);
Sylvain Berfini's avatar
Sylvain Berfini committed
757
LINPHONE_PUBLIC	int linphone_call_get_duration(const LinphoneCall *call);
758
LINPHONE_PUBLIC	const LinphoneCallParams * linphone_call_get_current_params(LinphoneCall *call);
759
LINPHONE_PUBLIC	const LinphoneCallParams * linphone_call_get_remote_params(LinphoneCall *call);
760 761
LINPHONE_PUBLIC void linphone_call_enable_camera(LinphoneCall *lc, bool_t enabled);
LINPHONE_PUBLIC bool_t linphone_call_camera_enabled(const LinphoneCall *lc);
762
LINPHONE_PUBLIC int linphone_call_take_video_snapshot(LinphoneCall *call, const char *file);
763
LINPHONE_PUBLIC int linphone_call_take_preview_snapshot(LinphoneCall *call, const char *file);
764
LINPHONE_PUBLIC	LinphoneReason linphone_call_get_reason(const LinphoneCall *call);
765
LINPHONE_PUBLIC const LinphoneErrorInfo *linphone_call_get_error_info(const LinphoneCall *call);
766
LINPHONE_PUBLIC	const char *linphone_call_get_remote_user_agent(LinphoneCall *call);
767
LINPHONE_PUBLIC	const char *linphone_call_get_remote_contact(LinphoneCall *call);
768 769 770

/**
 * Get the mesured playback volume level.
771
 *
772 773 774
 * @param call The call.
 * @return float Volume level in percentage.
 */
775
LINPHONE_PUBLIC	float linphone_call_get_play_volume(LinphoneCall *call);
776 777 778

/**
 * Get the mesured record volume level
779
 *
780 781 782
 * @param call The call.
 * @return float Volume level in percentage.
 */
783
LINPHONE_PUBLIC	float linphone_call_get_record_volume(LinphoneCall *call);
784

785
/**
786 787
 * Create a new chat room for messaging from a call if not already existing, else return existing one.
 * No reference is given to the caller: the chat room will be deleted when the call is ended.
788 789 790 791 792 793
 * @param call #LinphoneCall object
 * @return #LinphoneChatRoom where messaging can take place.
 */
LINPHONE_PUBLIC	struct _LinphoneChatRoom * linphone_call_get_chat_room(LinphoneCall *call);


794

795
/**
796
 * Get speaker volume gain.
797 798
 * If the sound backend supports it, the returned gain is equal to the gain set
 * with the system mixer.
799
 *
800
 * @param call The call.
801
 * @return Percenatge of the max supported volume gain. Valid values are in [ 0.0 : 1.0 ].
802 803
 * In case of failure, a negative value is returned
 */
804
LINPHONE_PUBLIC float linphone_call_get_speaker_volume_gain(const LinphoneCall *call);
805 806

/**
807
 * Set speaker volume gain.
808
 * If the sound backend supports it, the new gain will synchronized with the system mixer.
809
 *
810
 * @param call The call.
811
 * @param volume Percentage of the max supported gain. Valid values are in [ 0.0 : 1.0 ].
812
 */
813
LINPHONE_PUBLIC void linphone_call_set_speaker_volume_gain(LinphoneCall *call, float volume);
814 815

/**
816
 * Get microphone volume gain.
817 818
 * If the sound backend supports it, the returned gain is equal to the gain set
 * with the system mixer.
819
 *
820
 * @param call The call.
821
 * @return double Percenatge of the max supported volume gain. Valid values are in [ 0.0 : 1.0 ].
822 823
 * In case of failure, a negative value is returned
 */
824
LINPHONE_PUBLIC float linphone_call_get_microphone_volume_gain(const LinphoneCall *call);
825 826

/**
827
 * Set microphone volume gain.
828
 * If the sound backend supports it, the new gain will synchronized with the system mixer.
829
 *
830
 * @param call The call.
831
 * @param volume Percentage of the max supported gain. Valid values are in [ 0.0 : 1.0 ].
832
 */
833
LINPHONE_PUBLIC void linphone_call_set_microphone_volume_gain(LinphoneCall *call, float volume);
834

835 836 837 838 839
LINPHONE_PUBLIC	float linphone_call_get_current_quality(LinphoneCall *call);
LINPHONE_PUBLIC	float linphone_call_get_average_quality(LinphoneCall *call);
LINPHONE_PUBLIC	const char* linphone_call_get_authentication_token(LinphoneCall *call);
LINPHONE_PUBLIC	bool_t linphone_call_get_authentication_token_verified(LinphoneCall *call);
LINPHONE_PUBLIC	void linphone_call_set_authentication_token_verified(LinphoneCall *call, bool_t verified);
840
LINPHONE_PUBLIC void linphone_call_send_vfu_request(LinphoneCall *call);
841 842 843 844
/** @deprecated Use linphone_call_get_user_data() instead. */
#define linphone_call_get_user_pointer(call) linphone_call_get_user_data(call)
/** @deprecated Use linphone_call_set_user_data() instead. */
#define linphone_call_set_user_pointer(call, ud) linphone_call_set_user_data(call, ud)
845
LINPHONE_PUBLIC	void linphone_call_set_next_video_frame_decoded_callback(LinphoneCall *call, LinphoneCallCbFunc cb, void* user_data);
846 847
LINPHONE_PUBLIC LinphoneCallState linphone_call_get_transfer_state(LinphoneCall *call);
LINPHONE_PUBLIC void linphone_call_zoom_video(LinphoneCall* call, float zoom_factor, float* cx, float* cy);
848 849
LINPHONE_PUBLIC	void linphone_call_start_recording(LinphoneCall *call);
LINPHONE_PUBLIC	void linphone_call_stop_recording(LinphoneCall *call);
850
LINPHONE_PUBLIC LinphonePlayer * linphone_call_get_player(LinphoneCall *call);
Simon Morlat's avatar
Simon Morlat committed
851
LINPHONE_PUBLIC bool_t linphone_call_media_in_progress(LinphoneCall *call);
852 853 854 855 856 857
/**
 * Send the specified dtmf.
 *
 * The dtmf is automatically played to the user.
 * @param call The LinphoneCall object
 * @param dtmf The dtmf name specified as a char, such as '0', '#' etc...
858
 * @return 0 if successful, -1 on error.
859 860 861 862 863 864 865 866 867 868
**/
LINPHONE_PUBLIC	int linphone_call_send_dtmf(LinphoneCall *lc,char dtmf);

/**
 * Send a list of dtmf.
 *
 * The dtmfs are automatically sent to remote, separated by some needed customizable delay.
 * Sending is canceled if the call state changes to something not LinphoneCallStreamsRunning.
 * @param call The LinphoneCall object
 * @param dtmfs A dtmf sequence such as '123#123123'
869
 * @return -2 if there is already a DTMF sequence, -1 if call is not ready, 0 otherwise.
870 871 872 873 874 875 876 877 878 879 880 881 882
**/
LINPHONE_PUBLIC	int linphone_call_send_dtmfs(LinphoneCall *call,char *dtmfs);

/**
 * Stop current DTMF sequence sending.
 *
 * Please note that some DTMF could be already sent,
 * depending on when this function call is delayed from #linphone_call_send_dtmfs. This
 * function will be automatically called if call state change to anything but LinphoneCallStreamsRunning.
 *
 * @param call The LinphoneCall object
**/
LINPHONE_PUBLIC	void linphone_call_cancel_dtmfs(LinphoneCall *call);
883

884 885 886 887
/**
 * Get the native window handle of the video window, casted as an unsigned long.
 * @ingroup media_parameters
**/
888
LINPHONE_PUBLIC void * linphone_call_get_native_video_window_id(const LinphoneCall *call);
889 890 891 892 893 894

/**
 * Set the native video window id where the video is to be displayed.
 * For MacOS, Linux, Windows: if not set or 0 a window will be automatically created, unless the special id -1 is given.
 * @ingroup media_parameters
**/
895
LINPHONE_PUBLIC void linphone_call_set_native_video_window_id(LinphoneCall *call, void * id);
896

897 898
/**
 * Return TRUE if this call is currently part of a conference
899 900
 * @param call #LinphoneCall
 * @return TRUE if part of a conference.
901
 *
902
 * @deprecated Use linphone_call_get_conference() instead.
903
 * @ingroup call_control
904
 */
905
LINPHONE_PUBLIC	LINPHONE_DEPRECATED bool_t linphone_call_is_in_conference(const LinphoneCall *call);
906 907 908 909 910 911 912 913 914

/**
 * Return the associated conference object
 * @param call #LinphoneCall
 * @return A pointer on #LinphoneConference or NULL if the call is not part
 * of any conference.
 * @ingroup call_control
 */
LINPHONE_PUBLIC LinphoneConference *linphone_call_get_conference(const LinphoneCall *call);
jehan's avatar
jehan committed
915 916 917 918 919 920 921
/**
 * Enables or disable echo cancellation for this call
 * @param call
 * @param val
 *
 * @ingroup media_parameters
**/
922
LINPHONE_PUBLIC	void linphone_call_enable_echo_cancellation(LinphoneCall *call, bool_t val) ;
jehan's avatar
jehan committed
923 924 925 926 927
/**
 * Returns TRUE if echo cancellation is enabled.
 *
 * @ingroup media_parameters
**/
928
LINPHONE_PUBLIC	bool_t linphone_call_echo_cancellation_enabled(LinphoneCall *lc);
jehan's avatar
jehan committed
929 930 931 932 933 934 935
/**
 * Enables or disable echo limiter for this call
 * @param call
 * @param val
 *
 * @ingroup media_parameters
**/
936
LINPHONE_PUBLIC	void linphone_call_enable_echo_limiter(LinphoneCall *call, bool_t val);
jehan's avatar
jehan committed
937 938 939 940 941
/**
 * Returns TRUE if echo limiter is enabled.
 *
 * @ingroup media_parameters
**/
942
LINPHONE_PUBLIC	bool_t linphone_call_echo_limiter_enabled(const LinphoneCall *call);
Simon Morlat's avatar
Simon Morlat committed
943

944 945
/**
 * Enum describing type of audio route.
946
 * @ingroup call_control
947 948 949 950 951 952 953 954
**/
enum _LinphoneAudioRoute {
	LinphoneAudioRouteEarpiece = MSAudioRouteEarpiece,
	LinphoneAudioRouteSpeaker = MSAudioRouteSpeaker
};

/**
 * Enum describing type of audio route.
955
 * @ingroup call_control
956 957 958
**/
typedef enum _LinphoneAudioRoute LinphoneAudioRoute;

959 960 961 962
/**
 * Change the playback output device (currently only used for blackberry)
 * @param call
 * @param route the wanted audio route (earpiece, speaker, ...)
963
 *
964 965
 * @ingroup call_control
**/
966 967 968 969 970 971
LINPHONE_PUBLIC void linphone_call_set_audio_route(LinphoneCall *call, LinphoneAudioRoute route);

/**
 * Returns the number of stream for the given call.
 * Currently there is only two (Audio, Video), but later there will be more.
 * @param call
972
 *
973 974 975 976 977 978 979 980
 * @return 2
**/
LINPHONE_PUBLIC int linphone_call_get_stream_count(LinphoneCall *call);

/**
 * Returns the type of stream for the given stream index.
 * @param call
 * @param stream_index
981
 *
982
 * @return the type (MSAudio, MSVideo, MSText) of the stream of given index.
983 984 985 986 987 988 989
**/
LINPHONE_PUBLIC MSFormatType linphone_call_get_stream_type(LinphoneCall *call, int stream_index);

/**
 * Returns the meta rtp transport for the given stream index.
 * @param call
 * @param stream_index
990
 *
991 992 993 994 995 996 997 998
 * @return a pointer to the meta rtp transport if it exists, NULL otherwise
**/
LINPHONE_PUBLIC RtpTransport* linphone_call_get_meta_rtp_transport(LinphoneCall *call, int stream_index);

/**
 * Returns the meta rtcp transport for the given stream index.
 * @param call
 * @param stream_index
999
 *
1000 1001 1002
 * @return a pointer to the meta rtcp transport if it exists, NULL otherwise
**/
LINPHONE_PUBLIC RtpTransport* linphone_call_get_meta_rtcp_transport(LinphoneCall *call, int stream_index);
1003

Simon Morlat's avatar
Simon Morlat committed
1004
/*keep this in sync with mediastreamer2/msvolume.h*/
Simon Morlat's avatar
Simon Morlat committed
1005 1006 1007 1008 1009 1010

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

smorlat's avatar
smorlat committed
1012 1013 1014 1015
/**
 * @addtogroup proxies
 * @{
**/
1016

smorlat's avatar
smorlat committed
1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032
/**
 * 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.
**/
1033
typedef struct _LinphoneProxyConfig LinphoneProxyConfig;
aymeric's avatar
aymeric committed
1034

1035 1036 1037 1038
/**
 * LinphoneRegistrationState describes proxy registration states.
**/
typedef enum _LinphoneRegistrationState{
Simon Morlat's avatar
Simon Morlat committed
1039 1040 1041 1042 1043
	LinphoneRegistrationNone, /**<Initial state for registrations */
	LinphoneRegistrationProgress, /**<Registration is in progress */
	LinphoneRegistrationOk,	/**< Registration is successful */
	LinphoneRegistrationCleared, /**< Unregistration succeeded */
	LinphoneRegistrationFailed	/**<Registration failed */
1044 1045
}LinphoneRegistrationState;

1046 1047 1048 1049
/**
 * Human readable version of the #LinphoneRegistrationState
 * @param cs sate
 */
1050
LINPHONE_PUBLIC	const char *linphone_registration_state_to_string(LinphoneRegistrationState cs);
1051

1052 1053 1054 1055
/**
 * @}
 */

1056
#include "linphone_proxy_config.h"
smorlat's avatar
smorlat committed
1057 1058

/**
1059 1060
 * @addtogroup authentication
 * @{
smorlat's avatar
smorlat committed
1061 1062 1063 1064 1065 1066 1067 1068 1069 1070
 * 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
1071
 * order to become known and used automatically when needed.
smorlat's avatar
smorlat committed
1072 1073 1074 1075 1076 1077
 * 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.
 *
1078 1079
 * 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
1080 1081 1082
 * transactions and retry them with authentication headers.
 *
**/
1083
typedef struct _LinphoneAuthInfo LinphoneAuthInfo;
aymeric's avatar
aymeric committed
1084

1085
/**
1086
 * Creates a #_LinphoneAuthInfo object with supplied information.
1087 1088 1089 1090 1091 1092 1093 1094 1095
 * 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.
1096
 * @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
1097 1098
 * passed through linphone_core_add_auth_info().
**/
1099
LINPHONE_PUBLIC	LinphoneAuthInfo *linphone_auth_info_new(const char *username, const char *userid,
1100 1101
	const char *passwd, const char *ha1,const char *realm, const char *domain);

1102 1103
/**
 * @addtogroup authentication
1104
 * Instantiates a new auth info with values from source.
1105 1106
 * @param[in] source The #_LinphoneAuthInfo object to be cloned
 * @return The newly created #_LinphoneAuthInfo object.
1107 1108
 */
LINPHONE_PUBLIC	LinphoneAuthInfo *linphone_auth_info_clone(const LinphoneAuthInfo* source);
1109 1110 1111

/**
 * Sets the password.
1112
 * @param[in] info The #_LinphoneAuthInfo object
1113 1114
 * @param[in] passwd The password.
**/
Ghislain MARY's avatar
Ghislain MARY committed
1115
LINPHONE_PUBLIC void linphone_auth_info_set_passwd(LinphoneAuthInfo *info, const char *passwd);
1116 1117 1118

/**
 * Sets the username.
1119
 * @param[in] info The #_LinphoneAuthInfo object
1120 1121
 * @param[in] username The username.
**/
Ghislain MARY's avatar
Ghislain MARY committed
1122
LINPHONE_PUBLIC void linphone_auth_info_set_username(LinphoneAuthInfo *info, const char *username);
1123 1124 1125

/**
 * Sets the userid.
1126
 * @param[in] info The #_LinphoneAuthInfo object
1127 1128
 * @param[in] userid The userid.
**/
Ghislain MARY's avatar
Ghislain MARY committed
1129
LINPHONE_PUBLIC void linphone_auth_info_set_userid(LinphoneAuthInfo *info, const char *userid);
1130 1131 1132

/**
 * Sets the realm.
1133
 * @param[in] info The #_LinphoneAuthInfo object
1134 1135
 * @param[in] realm The realm.
**/
Ghislain MARY's avatar
Ghislain MARY committed
1136
LINPHONE_PUBLIC void linphone_auth_info_set_realm(LinphoneAuthInfo *info, const char *realm);
1137 1138 1139

/**
 * Sets the domain for which this authentication is valid.
1140
 * @param[in] info The #_LinphoneAuthInfo object
1141 1142 1143 1144
 * @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.
**/
1145
LINPHONE_PUBLIC void linphone_auth_info_set_domain(LinphoneAuthInfo *info, const char *domain);
1146 1147 1148

/**
 * Sets the ha1.
1149
 * @param[in] info The #_LinphoneAuthInfo object
1150 1151
 * @param[in] ha1 The ha1.
**/
Ghislain MARY's avatar
Ghislain MARY committed
1152 1153
LINPHONE_PUBLIC void linphone_auth_info_set_ha1(LinphoneAuthInfo *info, const char *ha1);

1154 1155 1156
/**
 * Gets the username.
 *
1157
 * @param[in] info The #_LinphoneAuthInfo object
1158 1159
 * @return The username.
 */
1160
LINPHONE_PUBLIC const char *linphone_auth_info_get_username(const LinphoneAuthInfo *info);
1161 1162 1163 1164

/**
 * Gets the password.
 *
1165
 * @param[in] info The #_LinphoneAuthInfo object
1166 1167
 * @return The password.
 */
1168
LINPHONE_PUBLIC const char *linphone_auth_info_get_passwd(const LinphoneAuthInfo *info);
1169 1170 1171 1172

/**
 * Gets the userid.
 *
1173
 * @param[in] info The #_LinphoneAuthInfo object
1174 1175
 * @return The userid.
 */
1176
LINPHONE_PUBLIC const char *linphone_auth_info_get_userid(const LinphoneAuthInfo *info);
1177 1178 1179 1180

/**
 * Gets the realm.
 *
1181
 * @param[in] info The #_LinphoneAuthInfo object
1182 1183
 * @return The realm.
 */
1184
LINPHONE_PUBLIC const char *linphone_auth_info_get_realm(const LinphoneAuthInfo *info);
1185 1186 1187 1188

/**
 * Gets the domain.
 *
1189
 * @param[in] info The #_LinphoneAuthInfo object
1190 1191
 * @return The domain.
 */
1192
LINPHONE_PUBLIC const char *linphone_auth_info_get_domain(const LinphoneAuthInfo *info);
1193 1194 1195 1196

/**
 * Gets the ha1.
 *
1197
 * @param[in] info The #_LinphoneAuthInfo object
1198 1199
 * @return The ha1.
 */
1200
LINPHONE_PUBLIC const char *linphone_auth_info_get_ha1(const LinphoneAuthInfo *info);
1201

aymeric's avatar
aymeric committed
1202
/* you don't need those function*/
1203 1204
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
1205

1206 1207 1208 1209
/**
 * @}
 */

jehan's avatar
jehan committed
1210

1211 1212
#ifdef IN_LINPHONE
#include "account_creator.h"
1213
#include "friendlist.h"
1214 1215
#else
#include "linphone/account_creator.h"
1216
#include "linphone/friendlist.h"
1217 1218 1219
#endif


jehan's avatar
jehan committed
1220 1221 1222 1223
/**
 * @addtogroup chatroom
 * @{
 */
1224 1225

/**
1226 1227 1228 1229 1230 1231
 * 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.
1232 1233 1234
 * <br> Can be created by linphone_chat_room_create_message().
 */
typedef struct _LinphoneChatMessage LinphoneChatMessage;
1235

jehan's avatar
jehan committed
1236 1237 1238 1239
/**
 * 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
1240
typedef struct _LinphoneChatRoom LinphoneChatRoom;
1241 1242

/**
1243
 * LinphoneChatMessageState is used to notify if messages have been succesfully delivered or not.
1244
 */
1245 1246 1247
typedef enum _LinphoneChatMessageState {
	LinphoneChatMessageStateIdle, /**< Initial state */
	LinphoneChatMessageStateInProgress, /**< Delivery in progress */
1248
	LinphoneChatMessageStateDelivered, /**< Message successfully delivered and acknowledged by remote end point */
1249
	LinphoneChatMessageStateNotDelivered, /**< Message was not delivered */
1250 1251
	LinphoneChatMessageStateFileTransferError, /**< Message was received(and acknowledged) but cannot get file from server */
	LinphoneChatMessageStateFileTransferDone /**< File transfer has been completed successfully. */
1252
} LinphoneChatMessageState;
1253 1254

/**
1255
 * Call back used to notify message delivery status
1256 1257 1258 1259
 * @param msg #LinphoneChatMessage object
 * @param status LinphoneChatMessageState
 * @param ud application user data
 * @deprecated
1260
 */
1261
typedef LINPHONE_DEPRECATED void (*LinphoneChatMessageStateChangedCb)(LinphoneChatMessage* msg,LinphoneChatMessageState state,void* ud);
1262

1263 1264 1265 1266 1267
/**
 * Call back used to notify message delivery status
 * @param msg #LinphoneChatMessage object
 * @param status LinphoneChatMessageState
 */
1268
typedef void (*LinphoneChatMessageCbsMsgStateChangedCb)(LinphoneChatMessage* msg, LinphoneChatMessageState state);
1269 1270 1271 1272 1273

/**
 * 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
1274
 * @param buffer #LinphoneBuffer holding the received data. Empty buffer means end of file.
1275
 */
1276
typedef void (*LinphoneChatMessageCbsFileTransferRecvCb)(LinphoneChatMessage *message, const LinphoneContent* content, const LinphoneBuffer *buffer);
1277 1278

/**
1279
 * 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.
1280 1281
 * @param message #LinphoneChatMessage message from which the body is received.
 * @param content #LinphoneContent outgoing content
1282 1283 1284
 * @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.
1285
 */
1286
typedef LinphoneBuffer * (*LinphoneChatMessageCbsFileTransferSendCb)(LinphoneChatMessage *message,  const LinphoneContent* content, size_t offset, size_t size);
1287 1288 1289 1290 1291 1292 1293 1294

/**
 * 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.
 */
1295
typedef void (*LinphoneChatMessageCbsFileTransferProgressIndicationCb)(LinphoneChatMessage *message, const LinphoneContent* content, size_t offset, size_t total);
1296

Ghislain MARY's avatar
Ghislain MARY committed
1297
LINPHONE_PUBLIC void linphone_core_set_chat_database_path(LinphoneCore *lc, const char *path);
Simon Morlat's avatar
Simon Morlat committed
1298 1299


1300 1301
/**
 * 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
1302
 * No reference is transfered to the application. The LinphoneCore keeps a reference on the chat room.
1303 1304 1305 1306
 * @param lc the linphone core
 * @param addr a linphone address.
 * @return #LinphoneChatRoom where messaging can take place.
**/
1307
LINPHONE_PUBLIC LinphoneChatRoom *linphone_core_get_chat_room(LinphoneCore *lc, const LinphoneAddress *addr);
1308 1309
/**
 * 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
1310
 * No reference is transfered to the application. The LinphoneCore keeps a reference on the chat room.
1311 1312 1313 1314
 * @param lc The linphone core
 * @param to The destination address for messages.
 * @return #LinphoneChatRoom where messaging can take place.
**/
1315
LINPHONE_PUBLIC LinphoneChatRoom *linphone_core_get_chat_room_from_uri(LinphoneCore *lc, const char *to);
Simon Morlat's avatar
Simon Morlat committed
1316 1317 1318 1319 1320 1321 1322 1323

/**
 * Removes a chatroom including all message history from the LinphoneCore.
 * @param lc The linphone core
 * @param to The chatroom.
**/
LINPHONE_PUBLIC void linphone_core_delete_chat_room(LinphoneCore *lc, LinphoneChatRoom *cr);

1324 1325 1326 1327 1328
/**
 * Inconditionnaly disable incoming chat messages.
 * @param lc the core
 * @param deny_reason the deny reason (#LinphoneReasonNone has no effect).
**/
1329
LINPHONE_PUBLIC void linphone_core_disable_chat(LinphoneCore *lc, LinphoneReason deny_reason);
1330 1331 1332 1333 1334
/**
 * Enable reception of incoming chat messages.
 * By default it is enabled but it can be disabled with linphone_core_disable_chat().
 * @param lc the core
**/
1335
LINPHONE_PUBLIC void linphone_core_enable_chat(LinphoneCore *lc);
1336 1337 1338
/**
 * Returns whether chat is enabled.
**/
1339
LINPHONE_PUBLIC bool_t linphone_core_chat_enabled(const LinphoneCore *lc);
1340 1341 1342 1343 1344
/**
 * Destroy a LinphoneChatRoom.
 * @param cr #LinphoneChatRoom object
 * @deprecated Use linphone_chat_room_unref() instead.
 */
1345
LINPHONE_PUBLIC LINPHONE_DEPRECATED void linphone_chat_room_destroy(LinphoneChatRoom *cr);
1346 1347 1348 1349 1350 1351
/**
 * 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
 */
1352
LINPHONE_PUBLIC	LinphoneChatMessage* linphone_chat_room_create_message(LinphoneChatRoom *cr,const char* message);
1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363
/**
 * Create a message attached to a dedicated chat room;
 * @par