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

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
17
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
aymeric's avatar
aymeric committed
18 19 20 21 22 23 24
*/
#ifndef LINPHONECORE_H
#define LINPHONECORE_H

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

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

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

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


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

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

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

59 60 61 62 63
/**
 * Safely down-cast a belle_sip_object_t into LinphoneCore
 * @ingroup initializing
 */
#define LINPHONE_CORE(object) BELLE_SIP_CAST(object, LinphoneCore)
64

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

/**
 * Don't create any server socket for this transport, ie don't bind on any port.
80
 * Use with #LinphoneSipTransports
Simon Morlat's avatar
Simon Morlat committed
81 82 83
 * @ingroup initializing
**/
#define LC_SIP_TRANSPORT_DONTBIND (-2)
84

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

110 111 112
/**
 * Old name of LinphoneSipTransports
 */
113
typedef struct _LinphoneSipTransports LCSipTransports;
114

115

116 117
/**
 * Enum describing transport type for LinphoneAddress.
118
 * @ingroup linphone_address
119 120 121 122 123 124 125 126 127
**/
enum _LinphoneTransportType{
	LinphoneTransportUdp,
	LinphoneTransportTcp,
	LinphoneTransportTls,
	LinphoneTransportDtls
};
/*this enum MUST be kept in sync with the SalTransport from sal.h*/

128 129 130 131
/**
 * Typedef for transport type enum.
 * @ingroup linphone_address
**/
132 133
typedef enum _LinphoneTransportType LinphoneTransportType;

134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149
/**
 * 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;
150

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

156
LINPHONE_PUBLIC const char *linphone_stream_type_to_string(const LinphoneStreamType);
157

158
#include "linphone/dictionary.h"
159
#include "linphone/error_info.h"
160

161 162 163 164 165 166 167 168 169 170 171 172 173 174 175
/**
 * Enum describing the authentication methods
 * @ingroup network_parameters
**/
enum _LinphoneAuthMethod {
	LinphoneAuthHttpDigest, /* Digest authentication requested */
	LinphoneAuthTls, /* Client certificate requested */
};

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

176

177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
/**
 * @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.
 */
206
LINPHONE_PUBLIC const char * linphone_payload_type_get_mime_type(const LinphonePayloadType *pt);
207 208 209 210 211 212 213 214

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

215

216 217 218 219 220 221 222 223 224 225 226 227 228 229
/**
 * 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;

230 231 232 233 234 235
/**
 * 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
236 237
	LinphoneMediaEncryptionZRTP, /**< Use ZRTP media encryption */
	LinphoneMediaEncryptionDTLS /**< Use DTLS media encryption */
238 239 240 241 242 243 244 245 246 247 248 249
};

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

250 251 252 253
/**
 * @}
**/

254

Simon Morlat's avatar
Simon Morlat committed
255 256 257
/*
 * Note for developers: this enum must be kept synchronized with the SalPrivacy enum declared in sal.h
 */
Simon Morlat's avatar
Simon Morlat committed
258
/**
jehan's avatar
jehan committed
259
 * @ingroup call_control
260
 * Defines privacy policy to apply as described by rfc3323
Simon Morlat's avatar
Simon Morlat committed
261
**/
jehan's avatar
jehan committed
262 263
typedef enum _LinphonePrivacy {
	/**
Simon Morlat's avatar
Simon Morlat committed
264
	 * Privacy services must not perform any privacy function
jehan's avatar
jehan committed
265
	 */
Simon Morlat's avatar
Simon Morlat committed
266
	LinphonePrivacyNone=0x0,
jehan's avatar
jehan committed
267
	/**
268
	 * Request that privacy services provide a user-level privacy
Simon Morlat's avatar
Simon Morlat committed
269 270
	 * function.
	 * With this mode, "from" header is hidden, usually replaced by  From: "Anonymous" <sip:anonymous@anonymous.invalid>
jehan's avatar
jehan committed
271
	 */
272
	LinphonePrivacyUser=0x1,
jehan's avatar
jehan committed
273
	/**
274
	 * Request that privacy services modify headers that cannot
Simon Morlat's avatar
Simon Morlat committed
275
	 * be set arbitrarily by the user (Contact/Via).
jehan's avatar
jehan committed
276
	 */
277
	LinphonePrivacyHeader=0x2,
Simon Morlat's avatar
Simon Morlat committed
278
	/**
279
	 *  Request that privacy services provide privacy for session
Simon Morlat's avatar
Simon Morlat committed
280 281
	 * media
	 */
282 283 284 285
	LinphonePrivacySession=0x4,
	/**
	 * rfc3325
	 * The presence of this privacy type in
Simon Morlat's avatar
Simon Morlat committed
286 287 288 289 290
	 * 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
291 292 293 294 295
	 *
	 */
	LinphonePrivacyId=0x8,
	/**
	 * Privacy service must perform the specified services or
Simon Morlat's avatar
Simon Morlat committed
296
	 * fail the request
297 298
	 *
	 **/
Simon Morlat's avatar
Simon Morlat committed
299
	LinphonePrivacyCritical=0x10,
300

Simon Morlat's avatar
Simon Morlat committed
301
	/**
Simon Morlat's avatar
Simon Morlat committed
302
	 * 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
303 304
	 */
	LinphonePrivacyDefault=0x8000,
jehan's avatar
jehan committed
305
} LinphonePrivacy;
306 307 308 309 310
/*
 * a mask  of #LinphonePrivacy values
 * */
typedef unsigned int LinphonePrivacyMask;

311 312

LINPHONE_PUBLIC const char* linphone_privacy_to_string(LinphonePrivacy privacy);
313 314


315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356
/**
 * Player interface.
 * @ingroup call_control
**/
typedef struct _LinphonePlayer LinphonePlayer;

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

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

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

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


357
#include "linphone/address.h"
358
#include "linphone/buffer.h"
359
#include "linphone/call.h"
360 361
#include "linphone/call_log.h"
#include "linphone/call_params.h"
362 363
#include "linphone/content.h"
#include "linphone/event.h"
364
#include "linphone/im_notif_policy.h"
365
#include "linphone/linphonefriend.h"
366
#include "linphone/nat_policy.h"
367
#include "linphone/xmlrpc.h"
368
#include "linphone/conference.h"
369 370 371 372 373 374 375 376 377 378

/**
 * 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
379 380 381 382 383
/**
 * The LinphoneInfoMessage is an object representing an informational message sent or received by the core.
**/
typedef struct _LinphoneInfoMessage LinphoneInfoMessage;

384 385 386 387 388 389 390 391
/**
 * Creates an empty info message.
 * @param lc the LinphoneCore
 * @return a new LinphoneInfoMessage.
 *
 * The info message can later be filled with information using linphone_info_message_add_header() or linphone_info_message_set_content(),
 * and finally sent with linphone_core_send_info_message().
**/
392
LINPHONE_PUBLIC LinphoneInfoMessage *linphone_core_create_info_message(LinphoneCore*lc);
393 394 395 396 397 398

/**
 * Send a LinphoneInfoMessage through an established call
 * @param call the call
 * @param info the info message
**/
399
LINPHONE_PUBLIC int linphone_call_send_info_message(struct _LinphoneCall *call, const LinphoneInfoMessage *info);
400 401 402 403 404 405 406

/**
 * Add a header to an info message to be sent.
 * @param im the info message
 * @param name the header'name
 * @param value the header's value
**/
Simon Morlat's avatar
Simon Morlat committed
407
LINPHONE_PUBLIC void linphone_info_message_add_header(LinphoneInfoMessage *im, const char *name, const char *value);
408 409 410 411 412 413 414

/**
 * Obtain a header value from a received info message.
 * @param im the info message
 * @param name the header'name
 * @return the corresponding header's value, or NULL if not exists.
**/
Simon Morlat's avatar
Simon Morlat committed
415
LINPHONE_PUBLIC const char *linphone_info_message_get_header(const LinphoneInfoMessage *im, const char *name);
416 417 418 419 420 421 422

/**
 * Assign a content to the info message.
 * @param im the linphone info message
 * @param content the content described as a #LinphoneContent structure.
 * All fields of the LinphoneContent are copied, thus the application can destroy/modify/recycloe the content object freely ater the function returns.
**/
Simon Morlat's avatar
Simon Morlat committed
423
LINPHONE_PUBLIC void linphone_info_message_set_content(LinphoneInfoMessage *im,  const LinphoneContent *content);
424 425 426 427

/**
 * Returns the info message's content as a #LinphoneContent structure.
**/
Simon Morlat's avatar
Simon Morlat committed
428
LINPHONE_PUBLIC const LinphoneContent * linphone_info_message_get_content(const LinphoneInfoMessage *im);
429 430 431 432

/**
 * Destroy a LinphoneInfoMessage
**/
Simon Morlat's avatar
Simon Morlat committed
433
LINPHONE_PUBLIC void linphone_info_message_destroy(LinphoneInfoMessage *im);
434
LINPHONE_PUBLIC LinphoneInfoMessage *linphone_info_message_copy(const LinphoneInfoMessage *orig);
Simon Morlat's avatar
Simon Morlat committed
435

436 437


438 439
/**
 * Structure describing policy regarding video streams establishments.
Simon Morlat's avatar
Simon Morlat committed
440
 * @ingroup media_parameters
441 442
**/
struct _LinphoneVideoPolicy{
443
	bool_t automatically_initiate; /**<Whether video shall be automatically proposed for outgoing calls.*/
444 445 446 447
	bool_t automatically_accept; /**<Whether video shall be automatically accepted for incoming calls*/
	bool_t unused[2];
};

Simon Morlat's avatar
Simon Morlat committed
448 449 450 451
/**
 * Structure describing policy regarding video streams establishments.
 * @ingroup media_parameters
**/
452 453
typedef struct _LinphoneVideoPolicy LinphoneVideoPolicy;

454

455 456


Simon Morlat's avatar
Simon Morlat committed
457 458 459 460 461
/**
 * @addtogroup call_misc
 * @{
**/

462 463 464
#define LINPHONE_CALL_STATS_AUDIO ((int)LinphoneStreamTypeAudio)
#define LINPHONE_CALL_STATS_VIDEO ((int)LinphoneStreamTypeVideo)
#define LINPHONE_CALL_STATS_TEXT  ((int)LinphoneStreamTypeText)
465

466 467 468 469 470
/**
 * Enum describing ICE states.
 * @ingroup initializing
**/
enum _LinphoneIceState{
Simon Morlat's avatar
Simon Morlat committed
471
	LinphoneIceStateNotActivated, /**< ICE has not been activated for this call or stream*/
Ghislain MARY's avatar
Ghislain MARY committed
472
	LinphoneIceStateFailed, /**< ICE processing has failed */
473 474 475 476 477 478 479 480 481 482 483 484
	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;

485 486
LINPHONE_PUBLIC const char *linphone_ice_state_to_string(LinphoneIceState state);

Yann Diorcet's avatar
Yann Diorcet committed
487 488 489 490 491 492 493 494 495 496 497 498
/**
 * 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 */
499
	LinphoneUpnpStateBlacklisted, /**< IGD router is blacklisted */
Yann Diorcet's avatar
Yann Diorcet committed
500 501 502 503 504 505 506 507
};

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

508

509 510 511 512
/**
 * Enum describing Ip family.
 * @ingroup initializing
**/
Erwan Croze's avatar
Erwan Croze committed
513 514 515 516
enum _LinphoneAddressFamily {
	LinphoneAddressFamilyInet, /* IpV4 */
	LinphoneAddressFamilyInet6, /* IpV6 */
	LinphoneAddressFamilyUnspec, /* Unknown */
517 518 519 520 521 522
};

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

Simon Morlat's avatar
Simon Morlat committed
525 526 527
/**
 * @}
**/
528

529 530
#include "linphone/call_stats.h"

Sylvain Berfini's avatar
Sylvain Berfini committed
531 532
LINPHONE_PUBLIC const LinphoneCallStats *linphone_call_get_audio_stats(LinphoneCall *call);
LINPHONE_PUBLIC const LinphoneCallStats *linphone_call_get_video_stats(LinphoneCall *call);
533
LINPHONE_PUBLIC const LinphoneCallStats *linphone_call_get_text_stats(LinphoneCall *call);
534

535 536 537 538 539 540
/**
 * 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
 */
541
LINPHONE_PUBLIC const LinphoneAddress * linphone_core_get_current_call_remote_address(LinphoneCore *lc);
542

543

Simon Morlat's avatar
Simon Morlat committed
544
/*keep this in sync with mediastreamer2/msvolume.h*/
Simon Morlat's avatar
Simon Morlat committed
545 546 547 548 549 550

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

smorlat's avatar
smorlat committed
552 553 554 555
/**
 * @addtogroup proxies
 * @{
**/
556

smorlat's avatar
smorlat committed
557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572
/**
 * 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.
**/
573
typedef struct _LinphoneProxyConfig LinphoneProxyConfig;
aymeric's avatar
aymeric committed
574

575 576 577 578
/**
 * LinphoneRegistrationState describes proxy registration states.
**/
typedef enum _LinphoneRegistrationState{
Simon Morlat's avatar
Simon Morlat committed
579 580 581 582 583
	LinphoneRegistrationNone, /**<Initial state for registrations */
	LinphoneRegistrationProgress, /**<Registration is in progress */
	LinphoneRegistrationOk,	/**< Registration is successful */
	LinphoneRegistrationCleared, /**< Unregistration succeeded */
	LinphoneRegistrationFailed	/**<Registration failed */
584 585
}LinphoneRegistrationState;

586

587 588 589 590
/**
 * Human readable version of the #LinphoneRegistrationState
 * @param cs sate
 */
591
LINPHONE_PUBLIC const char *linphone_registration_state_to_string(LinphoneRegistrationState cs);
592

593 594 595 596
/**
 * @}
 */

597
#include "linphone/account_creator.h"
598
#include "linphone/auth_info.h"
599
#include "linphone/friendlist.h"
600
#include "linphone/linphone_proxy_config.h"
Ghislain MARY's avatar
Ghislain MARY committed
601
#include "linphone/chat.h"
Simon Morlat's avatar
Simon Morlat committed
602 603 604 605 606 607 608 609 610 611 612


/**
 * @addtogroup initializing
 * @{
**/

/**
 * LinphoneGlobalState describes the global state of the LinphoneCore object.
 * It is notified via the LinphoneCoreVTable::global_state_changed
**/
613 614 615 616
typedef enum _LinphoneGlobalState{
	LinphoneGlobalOff,
	LinphoneGlobalStartup,
	LinphoneGlobalOn,
617 618
	LinphoneGlobalShutdown,
	LinphoneGlobalConfiguring
619 620
}LinphoneGlobalState;

621
LINPHONE_PUBLIC const char *linphone_global_state_to_string(LinphoneGlobalState gs);
aymeric's avatar
aymeric committed
622

623 624 625 626 627 628 629 630
/**
 * LinphoneCoreLogCollectionUploadState is used to notify if log collection upload have been succesfully delivered or not.
 */
typedef enum _LinphoneCoreLogCollectionUploadState {
	LinphoneCoreLogCollectionUploadStateInProgress, /**< Delivery in progress */
	LinphoneCoreLogCollectionUploadStateDelivered, /**< Log collection upload successfully delivered and acknowledged by remote end point */
	LinphoneCoreLogCollectionUploadStateNotDelivered, /**< Log collection upload was not delivered */
} LinphoneCoreLogCollectionUploadState;
631

jehan's avatar
jehan committed
632 633
LINPHONE_PUBLIC const char *linphone_core_log_collection_upload_state_to_string(const LinphoneCoreLogCollectionUploadState lcus);

Simon Morlat's avatar
Simon Morlat committed
634 635
/**
 * Global state notification callback.
636
 * @param lc the #LinphoneCore.
Simon Morlat's avatar
Simon Morlat committed
637 638 639
 * @param gstate the global state
 * @param message informational message.
 */
640 641 642 643 644
typedef void (*LinphoneCoreCbsGlobalStateChangedCb)(LinphoneCore *lc, LinphoneGlobalState gstate, const char *message);
/**
 * Old name of #LinphoneCoreCbsGlobalStateChangedCb.
 */
typedef LinphoneCoreCbsGlobalStateChangedCb LinphoneCoreGlobalStateChangedCb;
645 646 647 648 649
/**
 * Call state notification callback.
 * @param lc the LinphoneCore
 * @param call the call object whose state is changed.
 * @param cstate the new state of the call
650
 * @param message a non NULL informational message about the state.
651
 */
652 653 654 655 656
typedef void (*LinphoneCoreCbsCallStateChangedCb)(LinphoneCore *lc, LinphoneCall *call, LinphoneCallState cstate, const char *message);
/**
 * Old name of #LinphoneCoreCbsCallStateChangedCb.
 */
typedef LinphoneCoreCbsCallStateChangedCb LinphoneCoreCallStateChangedCb;
657 658 659 660 661 662 663 664

/**
 * Call encryption changed callback.
 * @param lc the LinphoneCore
 * @param call the call on which encryption is changed.
 * @param on whether encryption is activated.
 * @param authentication_token an authentication_token, currently set for ZRTP kind of encryption only.
 */
665 666 667 668 669
typedef void (*LinphoneCoreCbsCallEncryptionChangedCb)(LinphoneCore *lc, LinphoneCall *call, bool_t on, const char *authentication_token);
/**
 * Old name of #LinphoneCoreCbsCallEncryptionChangedCb.
 */
typedef LinphoneCoreCbsCallEncryptionChangedCb LinphoneCoreCallEncryptionChangedCb;
670

671 672 673
/** @ingroup Proxies
 * Registration state notification callback prototype
 * */
674 675 676 677 678 679
typedef void (*LinphoneCoreCbsRegistrationStateChangedCb)(LinphoneCore *lc, LinphoneProxyConfig *cfg, LinphoneRegistrationState cstate, const char *message) ;
/**
 * Old name of #LinphoneCoreCbsRegistrationStateChangedCb.
 */
typedef LinphoneCoreCbsRegistrationStateChangedCb LinphoneCoreRegistrationStateChangedCb;

680 681
/** Callback prototype
 * @deprecated
682
 */
683
typedef void (*ShowInterfaceCb)(LinphoneCore *lc) ;
684 685
/** Callback prototype
 * @deprecated
686
 */
687
typedef void (*DisplayStatusCb)(LinphoneCore *lc, const char *message) ;
688 689
/** Callback prototype
 * @deprecated
690
 */
691
typedef void (*DisplayMessageCb)(LinphoneCore *lc, const char *message) ;
692 693
/** Callback prototype
 * @deprecated
694
 */
695
typedef void (*DisplayUrlCb)(LinphoneCore *lc, const char *message, const char *url) ;
696
/** Callback prototype
697
 */
Simon Morlat's avatar
Simon Morlat committed
698
typedef void (*LinphoneCoreCbFunc)(LinphoneCore *lc,void * user_data);
jehan's avatar
jehan committed
699 700 701
/**
 * Report status change for a friend previously \link linphone_core_add_friend() added \endlink to #LinphoneCore.
 * @param lc #LinphoneCore object .
702 703
 * @param lf Updated #LinphoneFriend .
 */
704 705 706 707 708
typedef void (*LinphoneCoreCbsNotifyPresenceReceivedCb)(LinphoneCore *lc, LinphoneFriend * lf);
/**
 * Old name of #LinphoneCoreCbsNotifyPresenceReceivedCb.
 */
typedef LinphoneCoreCbsNotifyPresenceReceivedCb LinphoneCoreNotifyPresenceReceivedCb;
709 710 711 712 713 714 715
/**
 * Reports presence model change for a specific URI or phone number of a friend
 * @param lc #LinphoneCore object
 * @param lf #LinphoneFriend object
 * @param uri_or_tel The URI or phone number for which teh presence model has changed
 * @param presence_model The new presence model
 */
716 717 718 719 720
typedef void (*LinphoneCoreCbsNotifyPresenceReceivedForUriOrTelCb)(LinphoneCore *lc, LinphoneFriend *lf, const char *uri_or_tel, const LinphonePresenceModel *presence_model);
/**
 * Old name of #LinphoneCoreCbsNotifyPresenceReceivedForUriOrTelCb.
 */
typedef LinphoneCoreCbsNotifyPresenceReceivedForUriOrTelCb LinphoneCoreNotifyPresenceReceivedForUriOrTelCb;
721 722
/**
 *  Reports that a new subscription request has been received and wait for a decision.
723 724 725 726
 *  Status on this subscription request is notified by \link linphone_friend_set_inc_subscribe_policy() changing policy \endlink for this friend
 * @param lc #LinphoneCore object
 * @param lf #LinphoneFriend corresponding to the subscriber
 * @param url of the subscriber
727
 *  Callback prototype
728
 */
729 730 731 732 733
typedef void (*LinphoneCoreCbsNewSubscriptionRequestedCb)(LinphoneCore *lc, LinphoneFriend *lf, const char *url);
/**
 * Old name of #LinphoneCoreCbsNewSubscriptionRequestedCb.
 */
typedef LinphoneCoreCbsNewSubscriptionRequestedCb LinphoneCoreNewSubscriptionRequestedCb;
734
/**
735 736 737 738
 * Callback for requesting authentication information to application or user.
 * @param lc the LinphoneCore
 * @param realm the realm (domain) on which authentication is required.
 * @param username the username that needs to be authenticated.
739 740 741 742 743 744 745 746 747
 * @param domain the domain on which authentication is required.
 * Application shall reply to this callback using linphone_core_add_auth_info().
 */
typedef void (*LinphoneCoreAuthInfoRequestedCb)(LinphoneCore *lc, const char *realm, const char *username, const char *domain);

/**
 * Callback for requesting authentication information to application or user.
 * @param lc the LinphoneCore
 * @param auth_info a LinphoneAuthInfo pre-filled with username, realm and domain values as much as possible
748
 * @param method the type of authentication requested
749 750
 * Application shall reply to this callback using linphone_core_add_auth_info().
 */
751 752 753 754 755
typedef void (*LinphoneCoreCbsAuthenticationRequestedCb)(LinphoneCore *lc, LinphoneAuthInfo *auth_info, LinphoneAuthMethod method);
/**
 * Old name of #LinphoneCoreCbsAuthenticationRequestedCb.
 */
typedef LinphoneCoreCbsAuthenticationRequestedCb LinphoneCoreAuthenticationRequestedCb;
756

757
/**
758 759 760 761 762
 * Callback to notify a new call-log entry has been added.
 * This is done typically when a call terminates.
 * @param lc the LinphoneCore
 * @param newcl the new call log entry added.
 */
763 764 765 766 767
typedef void (*LinphoneCoreCbsCallLogUpdatedCb)(LinphoneCore *lc, LinphoneCallLog *newcl);
/**
 * Old name of #LinphoneCoreCbsCallLogUpdatedCb.
 */
typedef LinphoneCoreCbsCallLogUpdatedCb LinphoneCoreCallLogUpdatedCb;
768

jehan's avatar
jehan committed
769 770
/**
 * Callback prototype
771
 * @deprecated use #LinphoneCoreMessageReceivedCb instead.
jehan's avatar
jehan committed
772 773 774 775 776
 *
 * @param lc #LinphoneCore object
 * @param room #LinphoneChatRoom involved in this conversation. Can be be created by the framework in case \link #LinphoneAddress the from \endlink is not present in any chat room.
 * @param from #LinphoneAddress from
 * @param message incoming message
777
 */
778
typedef void (*LinphoneCoreTextMessageReceivedCb)(LinphoneCore *lc, LinphoneChatRoom *room, const LinphoneAddress *from, const char *message);
779

780 781 782 783 784 785
/**
 * Chat message callback prototype
 *
 * @param lc #LinphoneCore object
 * @param room #LinphoneChatRoom involved in this conversation. Can be be created by the framework in case \link #LinphoneAddress the from \endlink is not present in any chat room.
 * @param LinphoneChatMessage incoming message
786
 */
787 788 789 790 791
typedef void (*LinphoneCoreCbsMessageReceivedCb)(LinphoneCore *lc, LinphoneChatRoom *room, LinphoneChatMessage *message);
/**
 * Old name of #LinphoneCoreCbsMessageReceivedCb.
 */
typedef LinphoneCoreCbsMessageReceivedCb LinphoneCoreMessageReceivedCb;
792

793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824
/**
 * 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 lc #LinphoneCore object
 * @param message #LinphoneChatMessage message from which the body is received.
 * @param content #LinphoneContent incoming content information
 * @param buff pointer to the received data
 * @param size number of bytes to be read from buff. 0 means end of file.
 *
 */
typedef void (*LinphoneCoreFileTransferRecvCb)(LinphoneCore *lc, LinphoneChatMessage *message, const LinphoneContent* content, const char* buff, size_t size);

/**
 * File transfer send callback prototype. This function is called by the core upon an outgoing File transfer is started. This function is called until size is set to 0.
 * <br> a #LinphoneContent with a size equal zero
 *
 * @param lc #LinphoneCore object
 * @param message #LinphoneChatMessage message from which the body is received.
 * @param content #LinphoneContent outgoing content
 * @param buff pointer to the buffer where data chunk shall be written by the app
 * @param size as input value, it represents the number of bytes expected by the framework. As output value, it means the number of bytes wrote by the application in the buffer. 0 means end of file.
 *
 */
typedef void (*LinphoneCoreFileTransferSendCb)(LinphoneCore *lc, LinphoneChatMessage *message,  const LinphoneContent* content, char* buff, size_t* size);

/**
 * File transfer progress indication callback prototype.
 *
 * @param lc #LinphoneCore object
 * @param message #LinphoneChatMessage message from which the body is received.
 * @param content #LinphoneContent incoming content information
825 826
 * @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.
827
 */
828
typedef void (*LinphoneCoreFileTransferProgressIndicationCb)(LinphoneCore *lc, LinphoneChatMessage *message, const LinphoneContent* content, size_t offset, size_t total);
829

830 831 832 833 834 835
/**
 * Is composing notification callback prototype.
 *
 * @param[in] lc #LinphoneCore object
 * @param[in] room #LinphoneChatRoom involved in the conversation.
 */
836 837 838 839 840
typedef void (*LinphoneCoreCbsIsComposingReceivedCb)(LinphoneCore *lc, LinphoneChatRoom *room);
/**
 * Old name of #LinphoneCoreCbsIsComposingReceivedCb.
 */
typedef LinphoneCoreCbsIsComposingReceivedCb LinphoneCoreIsComposingReceivedCb;
841

842
/**
843 844 845 846 847
 * Callback for being notified of DTMFs received.
 * @param lc the linphone core
 * @param call the call that received the dtmf
 * @param dtmf the ascii code of the dtmf
 */
848 849 850 851 852
typedef void (*LinphoneCoreCbsDtmfReceivedCb)(LinphoneCore* lc, LinphoneCall *call, int dtmf);
/**
 * Old name of #LinphoneCoreCbsDtmfReceivedCb.
 */
typedef LinphoneCoreCbsDtmfReceivedCb LinphoneCoreDtmfReceivedCb;
853

smorlat's avatar
smorlat committed
854
/** Callback prototype */
855 856 857 858 859
typedef void (*LinphoneCoreCbsReferReceivedCb)(LinphoneCore *lc, const char *refer_to);
/**
 * Old name of #LinphoneCoreCbsReferReceivedCb.
 */
typedef LinphoneCoreCbsReferReceivedCb LinphoneCoreReferReceivedCb;
smorlat's avatar
smorlat committed
860
/** Callback prototype */
861 862 863 864 865
typedef void (*LinphoneCoreCbsBuddyInfoUpdatedCb)(LinphoneCore *lc, LinphoneFriend *lf);
/**
 * Old name of #LinphoneCoreCbsBuddyInfoUpdatedCb.
 */
typedef LinphoneCoreCbsBuddyInfoUpdatedCb LinphoneCoreBuddyInfoUpdatedCb;
866 867 868 869 870 871
/**
 * Callback for notifying progresses of transfers.
 * @param lc the LinphoneCore
 * @param transfered the call that was transfered
 * @param new_call_state the state of the call to transfer target at the far end.
 */
872 873 874 875 876
typedef void (*LinphoneCoreCbsTransferStateChangedCb)(LinphoneCore *lc, LinphoneCall *transfered, LinphoneCallState new_call_state);
/**
 * Old name of LinphoneCoreCbsTransferStateChangedCb.
 */
typedef LinphoneCoreCbsTransferStateChangedCb LinphoneCoreTransferStateChangedCb;
877

878
/**
879 880 881 882 883
 * Callback for receiving quality statistics for calls.
 * @param lc the LinphoneCore
 * @param call the call
 * @param stats the call statistics.
 */
884 885 886 887 888
typedef void (*LinphoneCoreCbsCallStatsUpdatedCb)(LinphoneCore *lc, LinphoneCall *call, const LinphoneCallStats *stats);
/**
 * Old name of #LinphoneCoreCbsCallStatsUpdatedCb.
 */
typedef LinphoneCoreCbsCallStatsUpdatedCb LinphoneCoreCallStatsUpdatedCb;
889

890
/**
891 892 893
 * Callback prototype for receiving info messages.
 * @param lc the LinphoneCore
 * @param call the call whose info message belongs to.
894
 * @param msg the info message.
895
 */
896 897 898 899 900
typedef void (*LinphoneCoreCbsInfoReceivedCb)(LinphoneCore *lc, LinphoneCall *call, const LinphoneInfoMessage *msg);
/**
 * Old name of #LinphoneCoreCbsInfoReceivedCb.
 */
typedef LinphoneCoreCbsInfoReceivedCb LinphoneCoreInfoReceivedCb;
901

902 903 904 905 906 907 908 909 910 911
/**
 * LinphoneGlobalState describes the global state of the LinphoneCore object.
 * It is notified via the LinphoneCoreVTable::global_state_changed
**/
typedef enum _LinphoneConfiguringState {
	LinphoneConfiguringSuccessful,
	LinphoneConfiguringFailed,
	LinphoneConfiguringSkipped
} LinphoneConfiguringState;

912 913 914 915 916 917
/**
 * Converts a _LinphoneConfiguringState enum to a string.
 * @ingroup misc
**/
LINPHONE_PUBLIC const char *linphone_configuring_state_to_string(LinphoneConfiguringState cs);

918 919 920 921 922
/**
 * Callback prototype for configuring status changes notification
 * @param lc the LinphoneCore
 * @param message informational message.
 */
923 924 925 926 927
typedef void (*LinphoneCoreCbsConfiguringStatusCb)(LinphoneCore *lc, LinphoneConfiguringState status, const char *message);
/**
 * Old name of #LinphoneCoreCbsConfiguringStatusCb.
 */
typedef LinphoneCoreCbsConfiguringStatusCb LinphoneCoreConfiguringStatusCb;
928

929 930 931 932 933
/**
 * Callback prototype for reporting network change either automatically detected or notified by #linphone_core_set_network_reachable.
 * @param lc the LinphoneCore
 * @param reachable true if network is reachable.
 */
934 935 936 937 938
typedef void (*LinphoneCoreCbsNetworkReachableCb)(LinphoneCore *lc, bool_t reachable);
/**
 * Old name of #LinphoneCoreCbsNetworkReachableCb.
 */
typedef LinphoneCoreCbsNetworkReachableCb LinphoneCoreNetworkReachableCb;
939

940 941 942 943 944 945
/**
 * Callback prototype for reporting log collection upload state change.
 * @param[in] lc LinphoneCore object
 * @param[in] state The state of the log collection upload
 * @param[in] info Additional information: error message in case of error state, URL of uploaded file in case of success.
 */
946 947 948 949 950
typedef void (*LinphoneCoreCbsLogCollectionUploadStateChangedCb)(LinphoneCore *lc, LinphoneCoreLogCollectionUploadState state, const char *info);
/**
 * Old name of #LinphoneCoreCbsLogCollectionUploadStateChangedCb.
 */
typedef LinphoneCoreCbsLogCollectionUploadStateChangedCb LinphoneCoreLogCollectionUploadStateChangedCb;
951 952 953 954 955

/**
 * Callback prototype for reporting log collection upload progress indication.
 * @param[in] lc LinphoneCore object
 */
956 957 958 959 960
typedef void (*LinphoneCoreCbsLogCollectionUploadProgressIndicationCb)(LinphoneCore *lc, size_t offset, size_t total);
/**
 * Old name of #LinphoneCoreCbsLogCollectionUploadProgressIndicationCb.
 */
typedef LinphoneCoreCbsLogCollectionUploadProgressIndicationCb LinphoneCoreLogCollectionUploadProgressIndicationCb;
961

962 963 964 965 966
/**
 * Callback prototype for reporting when a friend list has been added to the core friends list.
 * @param[in] lc LinphoneCore object
 * @param[in] list LinphoneFriendList object
 */
967 968 969 970 971
typedef void (*LinphoneCoreCbsFriendListCreatedCb) (LinphoneCore *lc, LinphoneFriendList *list);
/**
 * Old name of #LinphoneCoreCbsFriendListCreatedCb.
 */
typedef LinphoneCoreCbsFriendListCreatedCb LinphoneCoreFriendListCreatedCb;
972 973 974 975 976 977

/**
 * Callback prototype for reporting when a friend list has been removed from the core friends list.
 * @param[in] lc LinphoneCore object
 * @param[in] list LinphoneFriendList object
 */
978 979 980 981 982
typedef void (*LinphoneCoreCbsFriendListRemovedCb) (LinphoneCore *lc, LinphoneFriendList *list);
/**
 * Old name of #LinphoneCoreCbsFriendListRemovedCb.
 */
typedef LinphoneCoreCbsFriendListRemovedCb LinphoneCoreFriendListRemovedCb;
983

smorlat's avatar
smorlat committed
984 985
/**
 * This structure holds all callbacks that the application should implement.
986
 *  None is mandatory.
smorlat's avatar
smorlat committed
987
**/
Simon Morlat's avatar
Simon Morlat committed
988
typedef struct _LinphoneCoreVTable{
989 990 991
	LinphoneCoreGlobalStateChangedCb global_state_changed; /**<Notifies global state changes*/
	LinphoneCoreRegistrationStateChangedCb registration_state_changed;/**<Notifies registration state changes*/
	LinphoneCoreCallStateChangedCb call_state_changed;/**<Notifies call state changes*/
992
	LinphoneCoreNotifyPresenceReceivedCb notify_presence_received; /**< Notify received presence events*/
993
	LinphoneCoreNotifyPresenceReceivedForUriOrTelCb notify_presence_received_for_uri_or_tel; /**< Notify received presence events*/
994
	LinphoneCoreNewSubscriptionRequestedCb new_subscription_requested; /**< Notify about pending presence subscription request */
995 996
	LINPHONE_DEPRECATED LinphoneCoreAuthInfoRequestedCb auth_info_requested; /**< @deprecated Use authentication_requested instead. Ask the application some authentication information */
	LinphoneCoreAuthenticationRequestedCb authentication_requested; /**< Ask the application some authentication information */
997
	LinphoneCoreCallLogUpdatedCb call_log_updated; /**< Notifies that call log list has been updated */
998
	LinphoneCoreMessageReceivedCb message_received; /**< a message is received, can be text or external body*/
999
	LinphoneCoreIsComposingReceivedCb is_composing_received; /**< An is-composing notification has been received */
1000 1001 1002 1003 1004 1005 1006 1007
	LinphoneCoreDtmfReceivedCb dtmf_received; /**< A dtmf has been received received */
	LinphoneCoreReferReceivedCb refer_received; /**< An out of call refer was received */
	LinphoneCoreCallEncryptionChangedCb call_encryption_changed; /**<Notifies on change in the encryption of call streams */
	LinphoneCoreTransferStateChangedCb transfer_state_changed; /**<Notifies when a transfer is in progress */
	LinphoneCoreBuddyInfoUpdatedCb buddy_info_updated; /**< a LinphoneFriend's BuddyInfo has changed*/
	LinphoneCoreCallStatsUpdatedCb call_stats_updated; /**<Notifies on refreshing of call's statistics. */
	LinphoneCoreInfoReceivedCb info_received; /**<Notifies an incoming informational message received.*/
	LinphoneCoreSubscriptionStateChangedCb subscription_state_changed; /**<Notifies subscription state change */
1008
	LinphoneCoreNotifyReceivedCb notify_received; /**< Notifies a an event notification, see linphone_core_subscribe() */
1009
	LinphoneCorePublishStateChangedCb publish_state_changed;/**Notifies publish state change (only from #LinphoneEvent api)*/
1010
	LinphoneCoreConfiguringStatusCb configuring_status; /** Notifies configuring status changes */
1011 1012 1013 1014
	LINPHONE_DEPRECATED DisplayStatusCb display_status; /**< @deprecated Callback that notifies various events with human readable text.*/
	LINPHONE_DEPRECATED DisplayMessageCb display_message;/**< @deprecated Callback to display a message to the user */
	LINPHONE_DEPRECATED DisplayMessageCb display_warning;/**< @deprecated Callback to display a warning to the user */
	LINPHONE_DEPRECATED DisplayUrlCb display_url; /**< @deprecated */
1015
	LINPHONE_DEPRECATED ShowInterfaceCb show; /**< vNotifies the application that it should show up*/
1016 1017 1018 1019
	LINPHONE_DEPRECATED LinphoneCoreTextMessageReceivedCb text_received; /**< @deprecated, use #message_received instead <br> A text message has been received */
	LINPHONE_DEPRECATED LinphoneCoreFileTransferRecvCb file_transfer_recv; /**< @deprecated Callback to store file received attached to a #LinphoneChatMessage */
	LINPHONE_DEPRECATED LinphoneCoreFileTransferSendCb file_transfer_send; /**< @deprecated Callback to collect file chunk to be sent for a #LinphoneChatMessage */
	LINPHONE_DEPRECATED LinphoneCoreFileTransferProgressIndicationCb file_transfer_progress_indication; /**< @deprecated Callback to indicate file transfer progress */
1020 1021 1022
	LinphoneCoreNetworkReachableCb network_reachable; /**< Callback to report IP network status (I.E up/down )*/
	LinphoneCoreLogCollectionUploadStateChangedCb log_collection_upload_state_changed; /**< Callback to upload collected logs */
	LinphoneCoreLogCollectionUploadProgressIndicationCb log_collection_upload_progress_indication; /**< Callback to indicate log collection upload progress */
1023 1024
	LinphoneCoreFriendListCreatedCb friend_list_created;
	LinphoneCoreFriendListRemovedCb friend_list_removed;
Simon Morlat's avatar
Simon Morlat committed
1025
	void *user_data; /**<User data associated with the above callbacks */
aymeric's avatar
aymeric committed
1026 1027
} LinphoneCoreVTable;

1028
/**
1029
 * Instantiate a vtable with all arguments set to NULL
1030
 * @return newly allocated vtable
1031
 */
1032
LINPHONE_PUBLIC LinphoneCoreVTable *linphone_core_v_table_new(void);
1033

1034 1035 1036 1037 1038 1039 1040 1041 1042 1043
/**
 * Sets a user data pointer in the vtable.
 * @param table the vtable
 * @param data the user data to attach
 */
LINPHONE_PUBLIC void linphone_core_v_table_set_user_data(LinphoneCoreVTable *table, void *data);

/**
 * Gets a user data pointer in the vtable.
 * @param table the vtable
1044
 * @return the data attached to the vtable
1045
 */
1046
LINPHONE_PUBLIC void* linphone_core_v_table_get_user_data(const LinphoneCoreVTable *table);
1047 1048 1049 1050 1051

/**
 * Gets the current VTable.
 * This is meant only to be called from a callback to be able to get the user_data associated with the vtable that called the callback.
 * @param lc the linphonecore
1052
 * @return the vtable that called the last callback
1053 1054 1055
 */
LINPHONE_PUBLIC LinphoneCoreVTable *linphone_core_get_current_vtable(LinphoneCore *lc);

1056
/**
1057
 * Destroy a vtable.
1058
 * @param table to be destroyed
1059
 */
1060
LINPHONE_PUBLIC void linphone_core_v_table_destroy(LinphoneCoreVTable* table);
1061

1062 1063 1064 1065 1066 1067 1068 1069

/**
 * That class holds all the callbacks which are called by #LinphoneCore.
 *
 * Use linphone_factory_create_core_cbs() to create an instance. Then, call the
 * callback setters on the events you need to monitor and pass the object to
 * a #LinphoneCore instance through linphone_core_add_listener().
 *
1070
 * That class is inherited from belle_sip_object_t.
1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276
 */
typedef struct _LinphoneCoreCbs LinphoneCoreCbs;

/**
 * Increment the reference counter.
 */
LINPHONE_PUBLIC LinphoneCoreCbs *linphone_core_cbs_ref(LinphoneCoreCbs *cbs);

/**
 * Decrement the reference counter.
 */
LINPHONE_PUBLIC void linphone_core_cbs_unref(LinphoneCoreCbs *cbs);

/**
 * Set private data to be get from each callbacks.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_user_data(LinphoneCoreCbs *cbs, void *user_data);

/**
 * Get the user pointer.
 */
LINPHONE_PUBLIC void *linphone_core_cbs_get_user_data(LinphoneCoreCbs *cbs);

/**
 * Gets the current #LinphoneCoreCbs.
 * This is meant only to be called from a callback to be able to get the user_data associated with the #LinphoneCoreCbs that is calling the callback.
 * @param lc the linphonecore
 * @return the #LinphoneCoreCbs that has called the last callback
 */
LINPHONE_PUBLIC LinphoneCoreCbs *linphone_core_get_current_callbacks(const LinphoneCore *lc);

/**
 * Set the #LinphoneCoreCbsRegistrationStateChangedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_registration_state_changed(LinphoneCoreCbs *cbs, LinphoneCoreCbsRegistrationStateChangedCb cb);

/**
 * Set the #LinphoneCoreCbsCallStateChangedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_call_state_changed(LinphoneCoreCbs *cbs, LinphoneCoreCbsCallStateChangedCb cb);

/**
 * Set the #LinphoneCoreCbsNotifyPresenceReceivedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_notify_presence_received(LinphoneCoreCbs *cbs, LinphoneCoreCbsNotifyPresenceReceivedCb cb);

/**
 * Set the #LinphoneCoreCbsNotifyPresenceReceivedForUriOrTelCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_notify_presence_received_for_uri_or_tel(LinphoneCoreCbs *cbs, LinphoneCoreCbsNotifyPresenceReceivedForUriOrTelCb cb);

/**
 * Set the #LinphoneCoreCbsNewSubscriptionRequestedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_new_subscription_requested(LinphoneCoreCbs *cbs, LinphoneCoreCbsNewSubscriptionRequestedCb cb);

/**
 * Set the #LinphoneCoreCbsAuthenticationRequestedCb callback.'
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_authentication_requested(LinphoneCoreCbs *cbs, LinphoneCoreCbsAuthenticationRequestedCb cb);

/**
 * Set the #LinphoneCoreCbsCallLogUpdatedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_call_log_updated(LinphoneCoreCbs *cbs, LinphoneCoreCbsCallLogUpdatedCb cb);

/**
 * Set the #LinphoneCoreCbsMessageReceivedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_message_received(LinphoneCoreCbs *cbs, LinphoneCoreCbsMessageReceivedCb cb);

/**
 * Set the #LinphoneCoreCbsIsComposingReceivedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_is_composing_received(LinphoneCoreCbs *cbs, LinphoneCoreCbsIsComposingReceivedCb cb);

/**
 * Set the #LinphoneCoreCbsDtmfReceivedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_dtmf_received(LinphoneCoreCbs *cbs, LinphoneCoreCbsDtmfReceivedCb cb);

/**
 * Set the #LinphoneCoreCbsReferReceivedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_refer_received(LinphoneCoreCbs *cbs, LinphoneCoreCbsReferReceivedCb cb);

/**
 * Set the #LinphoneCoreCbsCallEncryptionChangedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_call_encryption_changed(LinphoneCoreCbs *cbs, LinphoneCoreCbsCallEncryptionChangedCb cb);

/**
 * Set the #LinphoneCoreCbsTransferStateChangedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_transfer_state_changed(LinphoneCoreCbs *cbs, LinphoneCoreCbsTransferStateChangedCb cb);

/**
 * Set the #LinphoneCoreCbsBuddyInfoUpdatedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_buddy_info_updated(LinphoneCoreCbs *cbs, LinphoneCoreCbsBuddyInfoUpdatedCb cb);

/**
 * Set the #LinphoneCoreCbsCallStatsUpdatedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_call_stats_updated(LinphoneCoreCbs *cbs, LinphoneCoreCbsCallStatsUpdatedCb cb);

/**
 * Set the #LinphoneCoreCbsInfoReceivedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_info_received(LinphoneCoreCbs *cbs, LinphoneCoreCbsInfoReceivedCb cb);

/**
 * Set the #LinphoneCoreCbsSubscriptionStateChangedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_subscription_state_changed(LinphoneCoreCbs *cbs, LinphoneCoreCbsSubscriptionStateChangedCb cb);

/**
 * Set the #LinphoneCoreCbsNotifyReceivedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_notify_received(LinphoneCoreCbs *cbs, LinphoneCoreCbsNotifyReceivedCb cb);

/**
 * Set the #LinphoneCoreCbsPublishStateChangedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_publish_state_changed(LinphoneCoreCbs *cbs, LinphoneCoreCbsPublishStateChangedCb cb);

/**
 * Set the #LinphoneCoreCbsConfiguringStatusCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_configuring_status(LinphoneCoreCbs *cbs, LinphoneCoreCbsConfiguringStatusCb cb);

/**
 * Set the #LinphoneCoreCbsNetworkReachableCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_network_reachable(LinphoneCoreCbs *cbs, LinphoneCoreCbsNetworkReachableCb cb);

/**
 * Set the #LinphoneCoreCbsLogCollectionUploadStateChangedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_log_collection_upload_state_changed(LinphoneCoreCbs *cbs, LinphoneCoreCbsLogCollectionUploadStateChangedCb cb);

/**
 * Set the #LinphoneCoreCbsLogCollectionUploadProgressIndicationCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_log_collection_upload_progress_indication(LinphoneCoreCbs *cbs, LinphoneCoreCbsLogCollectionUploadProgressIndicationCb cb);

/**
 * Set the #LinphoneCoreCbsFriendListCreatedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_friend_list_created(LinphoneCoreCbs *cbs, LinphoneCoreCbsFriendListCreatedCb cb);

/**
 * Set the #LinphoneCoreCbsFriendListRemovedCb callback.
 * @param[in] cbs A #LinphoneCoreCbs.
 * @param[in] cb The callback.
 */
LINPHONE_PUBLIC void linphone_core_cbs_set_friend_list_removed(LinphoneCoreCbs *cbs, LinphoneCoreCbsFriendListRemovedCb cb);

smorlat's avatar
smorlat committed
1277 1278 1279 1280
/**
 * @}
**/

aymeric's avatar
aymeric committed
1281 1282
typedef struct _LCCallbackObj
{
1283 1284
	LinphoneCoreCbFunc _func;
	void * _user_data;
aymeric's avatar
aymeric committed
1285 1286 1287
}LCCallbackObj;


1288 1289 1290
/**
 * Policy to use to pass through firewalls.
 * @ingroup network_parameters
1291
 * @deprecated Use #LinphoneNatPolicy instead.
1292 1293 1294 1295 1296 1297 1298
**/
typedef enum _LinphoneFirewallPolicy {
	LinphonePolicyNoFirewall, /**< Do not use any mechanism to pass through firewalls */
	LinphonePolicyUseNatAddress, /**< Use the specified public adress */
	LinphonePolicyUseStun, /**< Use a STUN server to get the public address */
	LinphonePolicyUseIce, /**< Use the ICE protocol */
	LinphonePolicyUseUpnp, /**< Use the uPnP protocol */
aymeric's avatar
aymeric committed
1299 1300
} LinphoneFirewallPolicy;

1301 1302 1303 1304 1305
typedef enum _LinphoneWaitingState{
	LinphoneWaitingStart,
	LinphoneWaitingProgress,
	LinphoneWaitingFinished
} LinphoneWaitingState;
1306
typedef void * (*LinphoneCoreWaitingCallback)(LinphoneCore *lc, void *context, LinphoneWaitingState ws, const char *purpose, float progress);
1307

aymeric's avatar
aymeric committed
1308 1309 1310

/* THE main API */

1311 1312 1313 1314 1315
/**
 * @addtogroup initializing
 * @{
**/

1316 1317 1318 1319 1320 1321
typedef enum _LinphoneLogCollectionState {
	LinphoneLogCollectionDisabled,
	LinphoneLogCollectionEnabled,
	LinphoneLogCollectionEnabledWithoutPreviousLogHandler
} LinphoneLogCollectionState;

1322 1323
/**
 * Tells whether the linphone core log collection is enabled.
1324
 * @return The state of the linphone core log collection.
1325 1326 1327
 */
LINPHONE_PUBLIC LinphoneLogCollectionState linphone_core_log_collection_enabled(void);

1328 1329
/**
 * Enable the linphone core log collection to upload logs on a server.
1330
 * @param[in] state LinphoneLogCollectionState value telling whether to enable log collection or not.
1331
 */
1332
LINPHONE_PUBLIC void linphone_core_enable_log_collection(LinphoneLogCollectionState state);
1333

1334 1335
/**
 * Get the path where the log files will be written for log collection.
1336
 * @return The path where the log files will be written.
1337 1338 1339
 */
LINPHONE_PUBLIC const char * linphone_core_get_log_collection_path(void);

1340 1341 1342 1343 1344 1345
/**
 * Set the path where the log files will be written for log collection.
 * @param[in] path The path where the log files will be written.
 */
LINPHONE_PUBLIC void linphone_core_set_log_collection_path(const char *path);

1346 1347
/**
 * Get the prefix of the filenames that will be used for log collection.
1348
 * @return The prefix of the filenames used for log collection.
1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359
 */
LINPHONE_PUBLIC const char * linphone_core_get_log_collection_prefix(void);

/**
 * Set the prefix of the filenames that will be used for log collection.
 * @param[in] prefix The prefix to use for the filenames for log collection.
 */
LINPHONE_PUBLIC void linphone_core_set_log_collection_prefix(const char *prefix);

/**
 * Get the max file size in bytes of the files used for log collection.
1360
 * @return The max file size in bytes of the files used for log collection.
1361
 */
1362
LINPHONE_PUBLIC size_t linphone_core_get_log_collection_max_file_size(void);
1363 1364 1365

/**
 * Set the max file size in bytes of the files used for log collection.
1366 1367 1368 1369
 * Warning: this function should only not be used to change size
 * dynamically but instead only before calling @see
 * linphone_core_enable_log_collection. If you increase max size
  * on runtime, logs chronological order COULD be broken.
1370 1371
 * @param[in] size The max file size in bytes of the files used for log collection.
 */
1372
LINPHONE_PUBLIC void linphone_core_set_log_collection_max_file_size(size_t size);
1373

1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386
/**
 * Set the url of the server where to upload the collected log files.
 * @param[in] core LinphoneCore object
 * @param[in] server_url The url of the server where to upload the collected log files.
 */
LINPHONE_PUBLIC void linphone_core_set_log_collection_upload_server_url(LinphoneCore *core, const char *server_url);

/**
 * Upload the log collection to the configured server url.
 * @param[in] core LinphoneCore object
 */
LINPHONE_PUBLIC void linphone_core_upload_log_collection(LinphoneCore *core);

1387 1388 1389 1390
/**
 * Compress the log collection in a single file.
 * @return The path of the compressed log collection file (to be freed calling ms_free()).
 */
1391
LINPHONE_PUBLIC char * linphone_core_compress_log_collection(void);
1392

1393 1394 1395
/**
 * Reset the log collection by removing the log files.
 */
1396
LINPHONE_PUBLIC void linphone_core_reset_log_collection(void);
1397

1398 1399 1400 1401 1402
/**
 * Define a log handler.
 *
 * @param logfunc The function pointer of the log handler.
 */
Ghislain MARY's avatar
Ghislain MARY committed
1403
LINPHONE_PUBLIC void linphone_core_set_log_handler(OrtpLogFunc logfunc);
1404

1405 1406 1407 1408 1409 1410 1411
/**
 * Define a log file.
 *
 * If the file pointer passed as an argument is NULL, stdout is used instead.
 *
 * @param file A pointer to the FILE structure of the file to write to.
 */
Ghislain MARY's avatar
Ghislain MARY committed
1412
LINPHONE_PUBLIC void linphone_core_set_log_file(FILE *file);
1413 1414

/**
1415
 * Define the minimum level for logging.
1416 1417
 *
 * @param loglevel Minimum level for logging messages.
1418
**/
1419
LINPHONE_PUBLIC void linphone_core_set_log_level(OrtpLogLevel loglevel);
1420

1421
/**
1422
 * Define the log level using mask.
1423 1424 1425 1426 1427 1428
 *
 * The loglevel parameter is a bitmask parameter. Therefore to enable only warning and error
 * messages, use ORTP_WARNING | ORTP_ERROR. To disable logs, simply set loglevel to 0.
 *
 * @param loglevel A bitmask of the log levels to set.
 */
1429
LINPHONE_PUBLIC void linphone_core_set_log_level_mask(unsigned int loglevel);
1430 1431 1432 1433 1434 1435 1436 1437 1438

/**
 * Enable logs in supplied FILE*.
 *
 * @deprecated Use #linphone_core_set_log_file and #linphone_core_set_log_level instead.
 *
 * @param file a C FILE* where to fprintf logs. If null stdout is used.
 *
**/
1439
LINPHONE_DEPRECATED LINPHONE_PUBLIC void linphone_core_enable_logs(FILE *file);
1440 1441 1442 1443 1444 1445 1446 1447 1448 1449

/**
 * Enable logs through the user's supplied log callback.
 *
 * @deprecated Use #linphone_core_set_log_handler and #linphone_core_set_log_level instead.
 *
 * @param logfunc The address of a OrtpLogFunc callback whose protoype is
 *            	  typedef void (*OrtpLogFunc)(OrtpLogLevel lev, const char *fmt, va_list args);
 *
**/
1450
LINPHONE_DEPRECATED LINPHONE_PUBLIC void linphone_core_enable_logs_with_cb(OrtpLogFunc logfunc);
1451 1452 1453 1454 1455 1456

/**
 * Entirely disable logging.
 *
 * @deprecated Use #linphone_core_set_log_level instead.
**/
1457
LINPHONE_DEPRECATED LINPHONE_PUBLIC void linphone_core_disable_logs(void);
1458 1459 1460 1461 1462 1463 1464

/**
 * Enable logs serialization (output logs from either the thread that creates the linphone core or the thread that calls linphone_core_iterate()).
 * Must be called before creating the linphone core.
 */
LINPHONE_PUBLIC void linphone_core_serialize_logs(void);

1465 1466 1467
/**
 * Returns liblinphone's version as a string.
**/
1468
LINPHONE_PUBLIC const char *linphone_core_get_version(void);
1469 1470 1471 1472

/**
 * @return liblinphone's user agent as a string.
**/
1473
LINPHONE_PUBLIC const char *linphone_core_get_user_agent(LinphoneCore *lc);
1474 1475 1476
/**
 * @deprecated Use #linphone_core_get_user_agent instead.
**/
1477
LINPHONE_PUBLIC LINPHONE_DEPRECATED const char *linphone_core_get_user_agent_name(void);
1478 1479 1480
/**
 * @deprecated Use #linphone_core_get_user_agent instead.
**/
1481
LINPHONE_PUBLIC LINPHONE_DEPRECATED const char *linphone_core_get_user_agent_version(void);
aymeric's avatar
aymeric committed
1482

1483 1484 1485 1486
/**
 * @}
**/

1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504
/**
 * Instanciates a LinphoneCore object.
 * @ingroup initializing
 *
 * The LinphoneCore object is the primary handle for doing all phone actions.
 * It should be unique within your application.
 * @param vtable a LinphoneCoreVTable structure holding your application callbacks
 * @param config_path a path to a config file. If it does not exists it will be created.
 *        The config file is used to store all settings, call logs, friends, proxies... so that all these settings
 *	       become persistent over the life of the LinphoneCore object.
 *	       It is allowed to set a NULL config file. In that case LinphoneCore will not store any settings.
 * @param factory_config_path a path to a read-only config file that can be used to
 *        to store hard-coded preference such as proxy settings or internal preferences.
 *        The settings in this factory file always override the one in the normal config file.
 *        It is OPTIONAL, use NULL if unneeded.
 * @param userdata an opaque user pointer that can be retrieved at any time (for example in
 *        callbacks) using linphone_core_get_user_data().
 * @see linphone_core_new_with_config
1505
 * @deprecated Use linphone_factory_create_core() instead.
1506
**/
1507
LINPHONE_DEPRECATED LINPHONE_PUBLIC LinphoneCore *linphone_core_new(const LinphoneCoreVTable *vtable,
1508
						const char *config_path, const char *factory_config_path, void* userdata);
aymeric's avatar
aymeric committed
1509

1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520
/**
 * Instantiates a LinphoneCore object with a given LpConfig.
 * @ingroup initializing
 *
 * The LinphoneCore object is the primary handle for doing all phone actions.
 * It should be unique within your application.
 * @param vtable a LinphoneCoreVTable structure holding your application callbacks
 * @param config a pointer to an LpConfig object holding the configuration of the LinphoneCore to be instantiated.
 * @param userdata an opaque user pointer that can be retrieved at any time (for example in
 *        callbacks) using linphone_core_get_user_data().
 * @see linphone_core_new
1521
 * @deprecated Use linphone_factory_create_core_with_config() instead.
1522
**/
1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539
LINPHONE_DEPRECATED LINPHONE_PUBLIC LinphoneCore *linphone_core_new_with_config(const LinphoneCoreVTable *vtable, LpConfig *config, void *userdata);

/**
 * Increment the reference counter of a #LinphoneCore object.
 * @param lc The #LinphoneCore which the ref counter is to be incremented.
 * @return A pointer on the #LinphoneCore passed as parameter.
 * @ingroup initializing
 */
LINPHONE_PUBLIC LinphoneCore *linphone_core_ref(LinphoneCore *lc);

/**
 * Decrement the ref counter of a #LinphoneCore object and destroy it
 * if the counter reach 0.
 * @param lc The #LinphoneCore which the reference counter is to be decreased.
 * @ingroup initializing
 */
LINPHONE_PUBLIC void linphone_core_unref(LinphoneCore *lc);
1540

1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552
/**
 * Main loop function. It is crucial that your application call it periodically.
 *
 * linphone_core_iterate() performs various backgrounds tasks:
 * - receiving of SIP messages
 * - handles timers and timeout
 * - performs registration to proxies
 * - authentication retries
 * The application MUST call this function periodically, in its main loop.
 * Be careful that this function must be called from the same thread as
 * other liblinphone methods. If it is not the case make sure all liblinphone calls are
 * serialized with a mutex.
1553
 * For ICE to work properly it should be called every 20ms.
1554
 * @param[in] lc LinphoneCore object
1555
 * @ingroup initializing
1556 1557
**/
LINPHONE_PUBLIC void linphone_core_iterate(LinphoneCore *lc);
1558

jehan's avatar
jehan committed
1559 1560
/**
 * @ingroup initializing
1561 1562
 * add a listener to be notified of linphone core events. Once events are received, registered vtable are invoked in order.
 * @param vtable a LinphoneCoreVTable structure holding your application callbacks. Object is owned by linphone core until linphone_core_remove_listener.
jehan's avatar
jehan committed
1563
 * @param lc object
1564
 * @deprecated Use linphone_core_add_callbacks() instead.
jehan's avatar
jehan committed
1565
 */
1566 1567 1568 1569 1570 1571 1572 1573 1574
LINPHONE_DEPRECATED LINPHONE_PUBLIC void linphone_core_add_listener(LinphoneCore *lc, LinphoneCoreVTable *vtable);
/**
 * @ingroup initializing
 * Add a listener in order to be notified of #LinphoneCore events. Once an event is received, registred #LinphoneCoreCbs are sequencially
 * invoked in order.
 * @param lc The #LinphoneCore object to monitor.
 * @param cbs A #LinphoneCoreCbs object holding the callbakcs you need. A reference is take by #LinphoneCore until you invoke linphone_core_remove_cbs().
 */
LINPHONE_PUBLIC void linphone_core_add_callbacks(LinphoneCore *lc, LinphoneCoreCbs *cbs);
jehan's avatar
jehan committed
1575 1576
/**
 * @ingroup initializing
1577 1578
 * remove a listener registred by linphone_core_add_listener.
 * @param lc object
1579 1580
 * @param vtable a LinphoneCoreVTable structure holding your application callbacks.
 * @deprecated Use linphone_core_remove_callbacks() instead.
jehan's avatar
jehan committed
1581
 */
1582 1583 1584 1585 1586 1587 1588 1589
LINPHONE_DEPRECATED LINPHONE_PUBLIC void linphone_core_remove_listener(LinphoneCore *lc, const LinphoneCoreVTable *vtable);
/**
 * @ingroup initializing
 * Remove a listener from a #LinphoneCore
 * @param lc The #LinphoneCore
 * @param cbs The pointer on the #LinphoneCoreCbs to remove.
 */
LINPHONE_PUBLIC void linphone_core_remove_callbacks(LinphoneCore *lc, const LinphoneCoreCbs *cbs);
jehan's avatar
jehan committed
1590

1591 1592 1593 1594 1595 1596 1597 1598
/**
 * Sets the user agent string used in SIP messages, ideally called just after linphone_core_new() or linphone_core_init().
 * @param[in] lc LinphoneCore object
 * @param[in] ua_name The user agent name
 * @param[in] version The user agent version
 * @ingroup misc
**/
LINPHONE_PUBLIC void linphone_core_set_user_agent(LinphoneCore *lc, const char *ua_name, const char *version);
1599

1600 1601 1602 1603 1604
/**
 * See linphone_proxy_config_normalize_sip_uri for documentation. Default proxy config is used to parse
 * the address.
 * @ingroup misc
 */
1605
LINPHONE_PUBLIC LinphoneAddress * linphone_core_interpret_url(LinphoneCore *lc, const char *url);
1606

1607 1608 1609