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"
Sylvain Berfini's avatar
Sylvain Berfini committed
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
#ifndef LINPHONE_PUBLIC
Simon Morlat's avatar
Simon Morlat committed
41
#define LINPHONE_PUBLIC MS2_PUBLIC
Sylvain Berfini's avatar
Sylvain Berfini committed
42 43
#endif

Simon Morlat's avatar
Simon Morlat committed
44 45
#ifndef LINPHONE_DEPRECATED
#define LINPHONE_DEPRECATED MS2_DEPRECATED
46
#endif
jehan's avatar
jehan committed
47 48


aymeric's avatar
aymeric committed
49 50 51 52 53
#ifdef __cplusplus
extern "C" {
#endif

struct _LinphoneCore;
54
struct _LinphoneChatRoom;
55 56 57
struct _LinphoneAuthInfo;
struct _SipSetupContext;
struct _LinphoneInfoMessage;
58

jehan's avatar
jehan committed
59 60 61 62 63
/**
 * Linphone core main object created by function linphone_core_new() .
 * @ingroup initializing
 */
typedef struct _LinphoneCore LinphoneCore;
aymeric's avatar
aymeric committed
64

65

66 67 68 69 70 71 72 73 74 75 76 77 78
/**
 * 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
79 80 81 82 83
/**
 * Linphone core SIP transport ports.
 * Use with #linphone_core_set_sip_transports
 * @ingroup initializing
 */
jehan's avatar
jehan committed
84
typedef struct _LCSipTransports{
jehan's avatar
jehan committed
85 86 87
	/**
	 * udp port to listening on, negative value if not set
	 * */
88
	int udp_port;
jehan's avatar
jehan committed
89 90 91
	/**
	 * tcp port to listening on, negative value if not set
	 * */
92
	int tcp_port;
jehan's avatar
jehan committed
93 94 95
	/**
	 * dtls port to listening on, negative value if not set
	 * */
96
	int dtls_port;
jehan's avatar
jehan committed
97 98 99
	/**
	 * tls port to listening on, negative value if not set
	 * */
100
	int tls_port;
jehan's avatar
jehan committed
101 102
} LCSipTransports;

103

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

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

122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
/**
 * 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;
138

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

144
LINPHONE_PUBLIC const char *linphone_stream_type_to_string(const LinphoneStreamType);
smorlat's avatar
smorlat committed
145 146 147 148 149 150 151 152 153 154
/**
 * 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.
155
 *
smorlat's avatar
smorlat committed
156 157
 * @ingroup linphone_address
 */
158
typedef struct SalAddress LinphoneAddress;
159

160 161
typedef struct belle_sip_dict LinphoneDictionary;

162 163 164 165 166 167 168 169 170 171 172
/**
 * 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;

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

204 205
#define LinphoneReasonBadCredentials LinphoneReasonForbidden

206 207 208
/*for compatibility*/
#define LinphoneReasonMedia LinphoneReasonUnsupportedContent

209 210 211 212 213 214 215 216 217 218
/**
 * Enum describing failure reasons.
 * @ingroup misc
**/
typedef enum _LinphoneReason LinphoneReason;

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

221 222 223 224 225 226 227 228 229 230 231 232
/**
 * 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);
233 234

/* linphone dictionary */
235
LINPHONE_PUBLIC	LinphoneDictionary* linphone_dictionary_new(void);
Ghislain MARY's avatar
Ghislain MARY committed
236 237 238
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);
239 240 241 242 243 244 245 246
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);
247
LINPHONE_PUBLIC int linphone_dictionary_haskey(const LinphoneDictionary* obj, const char* key);
248 249 250 251 252 253
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
254
LINPHONE_PUBLIC LinphoneDictionary* lp_config_section_to_dict( const LpConfig* lpconfig, const char* section );
255 256 257 258 259 260

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


264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292
/**
 * @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.
 */
293
LINPHONE_PUBLIC const char * linphone_payload_type_get_mime_type(const LinphonePayloadType *pt);
294 295 296 297 298 299 300 301

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

302

303 304 305 306 307 308 309 310 311 312 313 314 315 316
/**
 * 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;

317 318 319 320 321 322
/**
 * 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
323 324
	LinphoneMediaEncryptionZRTP, /**< Use ZRTP media encryption */
	LinphoneMediaEncryptionDTLS /**< Use DTLS media encryption */
325 326 327 328 329 330 331 332 333 334 335 336
};

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

337 338 339 340
/**
 * @}
**/

341

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

Simon Morlat's avatar
Simon Morlat committed
388
	/**
Simon Morlat's avatar
Simon Morlat committed
389
	 * 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
390 391
	 */
	LinphonePrivacyDefault=0x8000,
jehan's avatar
jehan committed
392
} LinphonePrivacy;
jehan's avatar
jehan committed
393 394 395 396 397
/*
 * a mask  of #LinphonePrivacy values
 * */
typedef unsigned int LinphonePrivacyMask;

Simon Morlat's avatar
Simon Morlat committed
398 399

LINPHONE_PUBLIC const char* linphone_privacy_to_string(LinphonePrivacy privacy);
Ghislain MARY's avatar
Ghislain MARY committed
400 401 402


#ifdef IN_LINPHONE
403
#include "buffer.h"
Ghislain MARY's avatar
Ghislain MARY committed
404 405
#include "call_log.h"
#include "call_params.h"
406 407 408
#include "content.h"
#include "event.h"
#include "linphonefriend.h"
409
#include "xmlrpc.h"
410
#include "conference.h"
Ghislain MARY's avatar
Ghislain MARY committed
411
#else
412
#include "linphone/buffer.h"
Ghislain MARY's avatar
Ghislain MARY committed
413 414
#include "linphone/call_log.h"
#include "linphone/call_params.h"
415 416 417
#include "linphone/content.h"
#include "linphone/event.h"
#include "linphone/linphonefriend.h"
418
#include "linphone/xmlrpc.h"
419
#include "linphone/conference.h"
Ghislain MARY's avatar
Ghislain MARY committed
420 421 422 423 424 425 426 427 428 429 430
#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);
431 432 433 434 435
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);
Ghislain MARY's avatar
Ghislain MARY committed
436 437
/*remove tags, params etc... so that it is displayable to the user*/
LINPHONE_PUBLIC	void linphone_address_clean(LinphoneAddress *uri);
438 439 440
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);
441
LINPHONE_PUBLIC bool_t linphone_address_is_sip(const LinphoneAddress *uri);
Ghislain MARY's avatar
Ghislain MARY committed
442
LINPHONE_PUBLIC LinphoneTransportType linphone_address_get_transport(const LinphoneAddress *uri);
443 444
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);
Ghislain MARY's avatar
Ghislain MARY committed
445 446 447
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);
448
LINPHONE_PUBLIC bool_t linphone_address_equal(const LinphoneAddress *a1, const LinphoneAddress *a2);
449 450 451
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);
Ghislain MARY's avatar
Ghislain MARY committed
452 453 454 455 456 457 458 459 460 461 462
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
463 464 465 466 467
/**
 * The LinphoneInfoMessage is an object representing an informational message sent or received by the core.
**/
typedef struct _LinphoneInfoMessage LinphoneInfoMessage;

468 469
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
470
LINPHONE_PUBLIC void linphone_info_message_add_header(LinphoneInfoMessage *im, const char *name, const char *value);
Simon Morlat's avatar
Simon Morlat committed
471
LINPHONE_PUBLIC const char *linphone_info_message_get_header(const LinphoneInfoMessage *im, const char *name);
Simon Morlat's avatar
Simon Morlat committed
472
LINPHONE_PUBLIC void linphone_info_message_set_content(LinphoneInfoMessage *im,  const LinphoneContent *content);
Simon Morlat's avatar
Simon Morlat committed
473
LINPHONE_PUBLIC const LinphoneContent * linphone_info_message_get_content(const LinphoneInfoMessage *im);
Simon Morlat's avatar
Simon Morlat committed
474
LINPHONE_PUBLIC void linphone_info_message_destroy(LinphoneInfoMessage *im);
475
LINPHONE_PUBLIC LinphoneInfoMessage *linphone_info_message_copy(const LinphoneInfoMessage *orig);
Simon Morlat's avatar
Simon Morlat committed
476

Simon Morlat's avatar
Simon Morlat committed
477 478


479 480
/**
 * Structure describing policy regarding video streams establishments.
Simon Morlat's avatar
Simon Morlat committed
481
 * @ingroup media_parameters
482 483
**/
struct _LinphoneVideoPolicy{
Guillaume BIENKOWSKI's avatar
Guillaume BIENKOWSKI committed
484
	bool_t automatically_initiate; /**<Whether video shall be automatically proposed for outgoing calls.*/
485 486 487 488
	bool_t automatically_accept; /**<Whether video shall be automatically accepted for incoming calls*/
	bool_t unused[2];
};

Simon Morlat's avatar
Simon Morlat committed
489 490 491 492
/**
 * Structure describing policy regarding video streams establishments.
 * @ingroup media_parameters
**/
493 494
typedef struct _LinphoneVideoPolicy LinphoneVideoPolicy;

495

Yann Diorcet's avatar
Yann Diorcet committed
496 497


Simon Morlat's avatar
Simon Morlat committed
498 499 500 501 502
/**
 * @addtogroup call_misc
 * @{
**/

503 504 505
#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
506

507 508 509 510 511
/**
 * Enum describing ICE states.
 * @ingroup initializing
**/
enum _LinphoneIceState{
Simon Morlat's avatar
Simon Morlat committed
512
	LinphoneIceStateNotActivated, /**< ICE has not been activated for this call or stream*/
Ghislain MARY's avatar
Ghislain MARY committed
513
	LinphoneIceStateFailed, /**< ICE processing has failed */
514 515 516 517 518 519 520 521 522 523 524 525
	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;

526 527
LINPHONE_PUBLIC const char *linphone_ice_state_to_string(LinphoneIceState state);

Yann Diorcet's avatar
Yann Diorcet committed
528 529 530 531 532 533 534 535 536 537 538 539
/**
 * 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
540
	LinphoneUpnpStateBlacklisted, /**< IGD router is blacklisted */
Yann Diorcet's avatar
Yann Diorcet committed
541 542 543 544 545 546 547 548
};

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

549

Ghislain MARY's avatar
Ghislain MARY committed
550 551
#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 */
552
#define LINPHONE_CALL_STATS_PERIODICAL_UPDATE (1 << 2) /**< Every seconds LinphoneCallStats object has been updated */
553

Simon Morlat's avatar
Simon Morlat committed
554 555 556
/**
 * The LinphoneCallStats objects carries various statistic informations regarding quality of audio or video streams.
 *
557
 * 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
558 559 560 561 562 563 564 565 566
 * 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.
 *
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
568
 * it passes for instantiating the LinphoneCore object (see linphone_core_new() ).
Simon Morlat's avatar
Simon Morlat committed
569 570 571 572 573 574 575 576 577
 *
 * 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.*/
578
	LinphoneIceState	ice_state; /**< State of ICE processing. */
Yann Diorcet's avatar
Yann Diorcet committed
579
	LinphoneUpnpState	upnp_state; /**< State of uPnP processing. */
580 581
	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*/
582 583
	float local_late_rate; /**<percentage of packet received too late over last second*/
	float local_loss_rate; /**<percentage of lost packet over last second*/
Ghislain MARY's avatar
Ghislain MARY committed
584
	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 */
585 586
	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*/
587
	rtp_stats_t rtp_stats; /**< RTP stats */
Simon Morlat's avatar
Simon Morlat committed
588
	bool_t rtcp_received_via_mux; /*private flag, for non-regression test only*/
Simon Morlat's avatar
Simon Morlat committed
589 590 591 592 593
};

/**
 * @}
**/
Yann Diorcet's avatar
Yann Diorcet committed
594

Sylvain Berfini's avatar
Sylvain Berfini committed
595 596
LINPHONE_PUBLIC const LinphoneCallStats *linphone_call_get_audio_stats(LinphoneCall *call);
LINPHONE_PUBLIC const LinphoneCallStats *linphone_call_get_video_stats(LinphoneCall *call);
597
LINPHONE_PUBLIC const LinphoneCallStats *linphone_call_get_text_stats(LinphoneCall *call);
598 599 600 601
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);
602
LINPHONE_PUBLIC rtp_stats_t linphone_call_stats_get_rtp_stats(const LinphoneCallStats *statss);
603
LINPHONE_PUBLIC uint64_t linphone_call_stats_get_late_packets_cumulative_number(const LinphoneCallStats *stats, LinphoneCall *call);
604 605 606 607
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);
Yann Diorcet's avatar
Yann Diorcet committed
608

609
/** Callback prototype */
610
typedef void (*LinphoneCallCbFunc)(LinphoneCall *call,void * user_data);
611

612 613 614 615 616 617 618 619 620 621 622 623 624 625
/**
 * 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);

626
LINPHONE_PUBLIC int linphone_player_open(LinphonePlayer *obj, const char *filename, LinphonePlayerEofCallback, void *user_data);
627 628 629 630 631 632 633 634
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);
635

636
/**
637
 * Create an independent media file player.
638
 * This player support WAVE and MATROSKA formats.
639
 * @param lc A LinphoneCore object
640 641
 * @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
642
 * @param window_id Id of the drawing window. Depend of video out
643 644
 * @return A pointer on the new instance. NULL if faild.
 */
Ghislain MARY's avatar
Ghislain MARY committed
645
LINPHONE_PUBLIC LinphonePlayer *linphone_core_create_local_player(LinphoneCore *lc, MSSndCard *snd_card, const char *video_out, void *window_id);
646

647
/**
648
 * Check whether Matroksa format is supported by the player
649 650
 * @return TRUE if it is supported
 */
651
LINPHONE_PUBLIC bool_t linphone_local_player_matroska_supported(void);
652

Simon Morlat's avatar
Simon Morlat committed
653 654 655 656 657
/**
 * 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
**/
658
typedef enum _LinphoneCallState{
Simon Morlat's avatar
Simon Morlat committed
659
	LinphoneCallIdle,					/**<Initial call state */
660 661 662 663 664 665 666 667 668 669 670 671 672 673
	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
674
	LinphoneCallUpdatedByRemote, /**<The call's parameters change is requested by remote end, used for example when video is added by remote */
675
	LinphoneCallIncomingEarlyMedia, /**<We are proposing early media to an incoming call */
676
	LinphoneCallUpdating, /**<A call update has been initiated by us */
677 678 679
	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)*/
680 681
} LinphoneCallState;

682
LINPHONE_PUBLIC	const char *linphone_call_state_to_string(LinphoneCallState cs);
683

684 685 686 687 688 689 690 691 692 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
/**
 * 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);

719 720 721 722 723 724
/**
 * 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
 */
725
LINPHONE_PUBLIC LinphoneCore *linphone_call_get_core(const LinphoneCall *call);
726

727
LINPHONE_PUBLIC	LinphoneCallState linphone_call_get_state(const LinphoneCall *call);
Ghislain MARY's avatar
Ghislain MARY committed
728
LINPHONE_PUBLIC bool_t linphone_call_asked_to_autoanswer(LinphoneCall *call);
729 730 731 732 733 734 735

/**
 * 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
736
LINPHONE_PUBLIC	const LinphoneAddress * linphone_core_get_current_call_remote_address(LinphoneCore *lc);
737

Sylvain Berfini's avatar
Sylvain Berfini committed
738 739 740
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);
741
LINPHONE_PUBLIC	LinphoneCallLog *linphone_call_get_call_log(const LinphoneCall *call);
742 743 744 745
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);
746
LINPHONE_PUBLIC	LinphoneCall *linphone_call_get_replaced_call(LinphoneCall *call);
Sylvain Berfini's avatar
Sylvain Berfini committed
747
LINPHONE_PUBLIC	int linphone_call_get_duration(const LinphoneCall *call);
748
LINPHONE_PUBLIC	const LinphoneCallParams * linphone_call_get_current_params(LinphoneCall *call);
749
LINPHONE_PUBLIC	const LinphoneCallParams * linphone_call_get_remote_params(LinphoneCall *call);
Ghislain MARY's avatar
Ghislain MARY committed
750 751
LINPHONE_PUBLIC void linphone_call_enable_camera(LinphoneCall *lc, bool_t enabled);
LINPHONE_PUBLIC bool_t linphone_call_camera_enabled(const LinphoneCall *lc);
752
LINPHONE_PUBLIC int linphone_call_take_video_snapshot(LinphoneCall *call, const char *file);
753
LINPHONE_PUBLIC int linphone_call_take_preview_snapshot(LinphoneCall *call, const char *file);
754
LINPHONE_PUBLIC	LinphoneReason linphone_call_get_reason(const LinphoneCall *call);
755
LINPHONE_PUBLIC const LinphoneErrorInfo *linphone_call_get_error_info(const LinphoneCall *call);
756
LINPHONE_PUBLIC	const char *linphone_call_get_remote_user_agent(LinphoneCall *call);
Sylvain Berfini's avatar
Sylvain Berfini committed
757
LINPHONE_PUBLIC	const char *linphone_call_get_remote_contact(LinphoneCall *call);
758 759 760

/**
 * Get the mesured playback volume level.
761
 *
762 763 764
 * @param call The call.
 * @return float Volume level in percentage.
 */
765
LINPHONE_PUBLIC	float linphone_call_get_play_volume(LinphoneCall *call);
766 767 768

/**
 * Get the mesured record volume level
769
 *
770 771 772
 * @param call The call.
 * @return float Volume level in percentage.
 */
773
LINPHONE_PUBLIC	float linphone_call_get_record_volume(LinphoneCall *call);
774

775
/**
776 777
 * 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.
778 779 780 781 782 783
 * @param call #LinphoneCall object
 * @return #LinphoneChatRoom where messaging can take place.
 */
LINPHONE_PUBLIC	struct _LinphoneChatRoom * linphone_call_get_chat_room(LinphoneCall *call);


784

785
/**
786
 * Get speaker volume gain.
787 788
 * If the sound backend supports it, the returned gain is equal to the gain set
 * with the system mixer.
789
 *
790
 * @param call The call.
791
 * @return Percenatge of the max supported volume gain. Valid values are in [ 0.0 : 1.0 ].
792 793
 * In case of failure, a negative value is returned
 */
794
LINPHONE_PUBLIC float linphone_call_get_speaker_volume_gain(const LinphoneCall *call);
795 796

/**
797
 * Set speaker volume gain.
798
 * If the sound backend supports it, the new gain will synchronized with the system mixer.
799
 *
800
 * @param call The call.
801
 * @param volume Percentage of the max supported gain. Valid values are in [ 0.0 : 1.0 ].
802
 */
803
LINPHONE_PUBLIC void linphone_call_set_speaker_volume_gain(LinphoneCall *call, float volume);
804 805

/**
806
 * Get microphone volume gain.
807 808
 * If the sound backend supports it, the returned gain is equal to the gain set
 * with the system mixer.
809
 *
810
 * @param call The call.
811
 * @return double Percenatge of the max supported volume gain. Valid values are in [ 0.0 : 1.0 ].
812 813
 * In case of failure, a negative value is returned
 */
814
LINPHONE_PUBLIC float linphone_call_get_microphone_volume_gain(const LinphoneCall *call);
815 816

/**
817
 * Set microphone volume gain.
818
 * If the sound backend supports it, the new gain will synchronized with the system mixer.
819
 *
820
 * @param call The call.
821
 * @param volume Percentage of the max supported gain. Valid values are in [ 0.0 : 1.0 ].
822
 */
823
LINPHONE_PUBLIC void linphone_call_set_microphone_volume_gain(LinphoneCall *call, float volume);
824

825 826 827 828 829
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);
830
LINPHONE_PUBLIC void linphone_call_send_vfu_request(LinphoneCall *call);
831 832 833 834
/** @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)
835
LINPHONE_PUBLIC	void linphone_call_set_next_video_frame_decoded_callback(LinphoneCall *call, LinphoneCallCbFunc cb, void* user_data);
836 837
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);
838 839
LINPHONE_PUBLIC	void linphone_call_start_recording(LinphoneCall *call);
LINPHONE_PUBLIC	void linphone_call_stop_recording(LinphoneCall *call);
840
LINPHONE_PUBLIC LinphonePlayer * linphone_call_get_player(LinphoneCall *call);
Simon Morlat's avatar
Simon Morlat committed
841
LINPHONE_PUBLIC bool_t linphone_call_media_in_progress(LinphoneCall *call);
842 843 844 845 846 847
/**
 * 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...
848
 * @return 0 if successful, -1 on error.
849 850 851 852 853 854 855 856 857 858
**/
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'
859
 * @return -2 if there is already a DTMF sequence, -1 if call is not ready, 0 otherwise.
860 861 862 863 864 865 866 867 868 869 870 871 872
**/
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);
Sylvain Berfini's avatar
Sylvain Berfini committed
873

874 875 876 877
/**
 * Get the native window handle of the video window, casted as an unsigned long.
 * @ingroup media_parameters
**/
Ghislain MARY's avatar
Ghislain MARY committed
878
LINPHONE_PUBLIC void * linphone_call_get_native_video_window_id(const LinphoneCall *call);
879 880 881 882 883 884

/**
 * 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
**/
Ghislain MARY's avatar
Ghislain MARY committed
885
LINPHONE_PUBLIC void linphone_call_set_native_video_window_id(LinphoneCall *call, void * id);
886

jehan's avatar
jehan committed
887 888
/**
 * Return TRUE if this call is currently part of a conference
889 890
 * @param call #LinphoneCall
 * @return TRUE if part of a conference.
jehan's avatar
jehan committed
891
 *
892
 * @deprecated Use linphone_call_get_conference() instead.
893
 * @ingroup call_control
jehan's avatar
jehan committed
894
 */
Simon Morlat's avatar
Simon Morlat committed
895
LINPHONE_PUBLIC	LINPHONE_DEPRECATED bool_t linphone_call_is_in_conference(const LinphoneCall *call);
896 897 898 899 900 901 902 903 904

/**
 * 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
905 906 907 908 909 910 911
/**
 * Enables or disable echo cancellation for this call
 * @param call
 * @param val
 *
 * @ingroup media_parameters
**/
912
LINPHONE_PUBLIC	void linphone_call_enable_echo_cancellation(LinphoneCall *call, bool_t val) ;
jehan's avatar
jehan committed
913 914 915 916 917
/**
 * Returns TRUE if echo cancellation is enabled.
 *
 * @ingroup media_parameters
**/
918
LINPHONE_PUBLIC	bool_t linphone_call_echo_cancellation_enabled(LinphoneCall *lc);
jehan's avatar
jehan committed
919 920 921 922 923 924 925
/**
 * Enables or disable echo limiter for this call
 * @param call
 * @param val
 *
 * @ingroup media_parameters
**/
926
LINPHONE_PUBLIC	void linphone_call_enable_echo_limiter(LinphoneCall *call, bool_t val);
jehan's avatar
jehan committed
927 928 929 930 931
/**
 * Returns TRUE if echo limiter is enabled.
 *
 * @ingroup media_parameters
**/
932
LINPHONE_PUBLIC	bool_t linphone_call_echo_limiter_enabled(const LinphoneCall *call);
Simon Morlat's avatar
Simon Morlat committed
933

934 935
/**
 * Enum describing type of audio route.
936
 * @ingroup call_control
937 938 939 940 941 942 943 944
**/
enum _LinphoneAudioRoute {
	LinphoneAudioRouteEarpiece = MSAudioRouteEarpiece,
	LinphoneAudioRouteSpeaker = MSAudioRouteSpeaker
};

/**
 * Enum describing type of audio route.
945
 * @ingroup call_control
946 947 948
**/
typedef enum _LinphoneAudioRoute LinphoneAudioRoute;

949 950 951 952
/**
 * Change the playback output device (currently only used for blackberry)
 * @param call
 * @param route the wanted audio route (earpiece, speaker, ...)
953
 *
954 955
 * @ingroup call_control
**/
956 957 958 959 960 961
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
962
 *
963 964 965 966 967 968 969 970
 * @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
971
 *
972
 * @return the type (MSAudio, MSVideo, MSText) of the stream of given index.
973 974 975 976 977 978 979
**/
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
980
 *
981 982 983 984 985 986 987 988
 * @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
989
 *
990 991 992
 * @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);
993

Simon Morlat's avatar
Simon Morlat committed
994
/*keep this in sync with mediastreamer2/msvolume.h*/
Simon Morlat's avatar
Simon Morlat committed
995 996 997 998 999 1000

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

smorlat's avatar
smorlat committed
1002 1003 1004 1005
/**
 * @addtogroup proxies
 * @{
**/
1006

smorlat's avatar
smorlat committed
1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022
/**
 * 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