factory.h 20.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
/*
linphone
Copyright (C) 2016 Belledonne Communications <info@belledonne-communications.com>

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., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
*/

#ifndef LINPHONE_FACTORY_H
#define LINPHONE_FACTORY_H

23
#include "linphone/types.h"
24

25
#ifdef __cplusplus
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
extern "C" {
#endif

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

/**
 * Create the #LinphoneFactory if that has not been done and return
 * a pointer on it.
 * @return A pointer on the #LinphoneFactory
 */
LINPHONE_PUBLIC LinphoneFactory *linphone_factory_get(void);

Simon Morlat's avatar
Simon Morlat committed
41 42 43 44 45 46
/**
 * Clean the factory. This function is generally useless as the factory is unique per process, however
 * calling this function at the end avoid getting reports from belle-sip leak detector about memory leaked in linphone_factory_get().
 */
LINPHONE_PUBLIC void linphone_factory_clean(void);

47 48 49
/**
 * Instanciate a #LinphoneCore object.
 *
50
 * The #LinphoneCore object is the primary handle for doing all phone actions.
51 52 53 54 55 56 57 58 59 60 61 62 63 64
 * It should be unique within your application.
 * @param factory The #LinphoneFactory singleton.
 * @param cbs a #LinphoneCoreCbs object holding your application callbacks. A reference
 * will be taken on it until the destruciton of the core or the unregistration
 * with linphone_core_remove_cbs().
 * @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.
 * @see linphone_core_new_with_config
65
 * @deprecated 2018-01-10: Use linphone_factory_create_core_3() instead
66
 */
67 68 69 70 71 72
LINPHONE_DEPRECATED LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core(
	const LinphoneFactory *factory,
	LinphoneCoreCbs *cbs,
	const char *config_path,
	const char *factory_config_path
);
73 74 75 76

/**
 * Instanciate a #LinphoneCore object.
 *
77
 * The #LinphoneCore object is the primary handle for doing all phone actions.
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
 * It should be unique within your application.
 * @param factory The #LinphoneFactory singleton.
 * @param cbs a #LinphoneCoreCbs object holding your application callbacks. A reference
 * will be taken on it until the destruciton of the core or the unregistration
 * with linphone_core_remove_cbs().
 * @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 user_data an application pointer associated with the returned core.
 * @param system_context a pointer to a system object required by the core to operate. Currently it is required to pass an android Context on android, pass NULL on other platforms.
 * @see linphone_core_new_with_config
94
 * @deprecated 2018-01-10: Use linphone_factory_create_core_3() instead
95
 */
96 97 98 99 100 101 102 103
LINPHONE_DEPRECATED LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core_2 (
	const LinphoneFactory *factory,
	LinphoneCoreCbs *cbs,
	const char *config_path,
	const char *factory_config_path,
	void *user_data,
	void *system_context
);
104

105 106 107
/**
 * Instantiate a #LinphoneCore object.
 *
108
 * The #LinphoneCore object is the primary handle for doing all phone actions. It should be unique within your
109
 * application.
110
 * The #LinphoneCore object is not started automatically, you need to call linphone_core_start() to that effect.
111 112
 * @param[in] factory The #LinphoneFactory singleton.
 * @param[in] config_path A path to a config file. If it does not exists it will be created. The config file is used to
113 114
 * store all settings, 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.
115 116 117 118 119 120 121 122 123 124 125 126 127
 * @param[in] factory_config_path A path to a read-only config file that can be used to store hard-coded preferences
 * such as proxy settings or internal preferences. The settings in this factory file always override the ones in the
 * normal config file. It is optional, use NULL if unneeded.
 * @param[in] system_context A pointer to a system object required by the core to operate. Currently it is required to
 * pass an android Context on android, pass NULL on other platforms.
 * @see linphone_core_new_with_config_3
 */
LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core_3 (
	const LinphoneFactory *factory,
	const char *config_path,
	const char *factory_config_path,
	void *system_context
);
128

129
/**
130
 * Instantiates a #LinphoneCore object with a given LpConfig.
131 132
 *
 * @param factory The #LinphoneFactory singleton.
133
 * The #LinphoneCore object is the primary handle for doing all phone actions.
134 135 136 137
 * It should be unique within your application.
 * @param cbs a #LinphoneCoreCbs object holding your application callbacks. A reference
 * will be taken on it until the destruciton of the core or the unregistration
 * with linphone_core_remove_cbs().
138
 * @param config a pointer to an LpConfig object holding the configuration of the #LinphoneCore to be instantiated.
139
 * @see linphone_core_new
140
 * @deprecated 2018-01-10: Use linphone_factory_create_core_with_config_3() instead
141
 */
142 143 144 145 146
LINPHONE_DEPRECATED LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core_with_config (
	const LinphoneFactory *factory,
	LinphoneCoreCbs *cbs,
	LinphoneConfig *config
);
147

148
/**
149
 * Instantiates a #LinphoneCore object with a given LpConfig.
150 151
 *
 * @param factory The #LinphoneFactory singleton.
152
 * The #LinphoneCore object is the primary handle for doing all phone actions.
153 154 155 156
 * It should be unique within your application.
 * @param cbs a #LinphoneCoreCbs object holding your application callbacks. A reference
 * will be taken on it until the destruciton of the core or the unregistration
 * with linphone_core_remove_cbs().
157
 * @param config a pointer to an LpConfig object holding the configuration of the #LinphoneCore to be instantiated.
158 159 160
 * @param user_data an application pointer associated with the returned core.
 * @param system_context a pointer to a system object required by the core to operate. Currently it is required to pass an android Context on android, pass NULL on other platforms.
 * @see linphone_core_new
161 162 163 164 165 166 167 168 169 170 171
 * @deprecated 2018-01-10: Use linphone_factory_create_core_with_config_3() instead
 */
LINPHONE_DEPRECATED LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core_with_config_2 (
	const LinphoneFactory *factory,
	LinphoneCoreCbs *cbs,
	LinphoneConfig *config,
	void *user_data,
	void *system_context
);

/**
172
 * Instantiate a #LinphoneCore object with a given LinphoneConfig.
173
 *
174
 * The #LinphoneCore object is the primary handle for doing all phone actions. It should be unique within your
175
 * application.
176
 * The #LinphoneCore object is not started automatically, you need to call linphone_core_start() to that effect.
177
 * @param[in] factory The #LinphoneFactory singleton.
178
 * @param[in] config A #LinphoneConfig object holding the configuration for the #LinphoneCore to be instantiated.
179 180 181
 * @param[in] system_context A pointer to a system object required by the core to operate. Currently it is required to
 * pass an android Context on android, pass NULL on other platforms.
 * @see linphone_factory_create_core_3
182
 */
183 184 185 186 187
LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core_with_config_3 (
	const LinphoneFactory *factory,
	LinphoneConfig *config,
	void *system_context
);
188

189 190
/**
 * Instanciate a #LinphoneCoreCbs object.
191
 * @return a new #LinphoneCoreCbs.
192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214
 */
LINPHONE_PUBLIC LinphoneCoreCbs *linphone_factory_create_core_cbs(const LinphoneFactory *factory);

/**
 * Parse a string holding a SIP URI and create the according #LinphoneAddress object.
 * @param factory The #LinphoneFactory singleton.
 * @param addr A string holding the SIP URI to parse.
 * @return A new #LinphoneAddress.
 */
LINPHONE_PUBLIC LinphoneAddress *linphone_factory_create_address(const LinphoneFactory *factory, const char *addr);

/**
 * Creates a #LinphoneAuthInfo object.
 * The object can be created empty, that is with all arguments set to NULL.
 * Username, userid, password, realm and domain can be set later using specific methods.
 * At the end, username and passwd (or ha1) are required.
 * @param factory The #LinphoneFactory singleton.
 * @param username The username that needs to be authenticated
 * @param userid The userid used for authenticating (use NULL if you don't know what it is)
 * @param passwd The password in clear text
 * @param ha1 The ha1-encrypted password if password is not given in clear text.
 * @param realm The authentication domain (which can be larger than the sip domain. Unfortunately many SIP servers don't use this parameter.
 * @param domain The SIP domain for which this authentication information is valid, if it has to be restricted for a single SIP domain.
215
 * @return A #LinphoneAuthInfo object. linphone_auth_info_destroy() must be used to destroy it when no longer needed. The #LinphoneCore makes a copy of #LinphoneAuthInfo
216 217 218 219
 * passed through linphone_core_add_auth_info().
 */
LINPHONE_PUBLIC LinphoneAuthInfo *linphone_factory_create_auth_info(const LinphoneFactory *factory, const char *username, const char *userid, const char *passwd, const char *ha1, const char *realm, const char *domain);

220
/**
221 222 223
 * Create a #LinphoneCallCbs object that holds callbacks for events happening on a call.
 * @param[in] factory #LinphoneFactory singletion object
 * @return A new #LinphoneCallCbs object
224 225 226
 */
LINPHONE_PUBLIC LinphoneCallCbs * linphone_factory_create_call_cbs(const LinphoneFactory *factory);

227 228 229 230 231 232 233
/**
 * Create a LinphoneChatRoomCbs object that holds callbacks for events happening on a chat room.
 * @param[in] factory LinphoneFactory singletion object
 * @return A new LinphoneChatRoomCbs object
 */
LINPHONE_PUBLIC LinphoneChatRoomCbs * linphone_factory_create_chat_room_cbs(const LinphoneFactory *factory);

234 235 236 237 238 239 240
/**
 * Create an empty #LinphoneVcard.
 * @return a new #LinphoneVcard.
 * @ingroup initializing
 */
LINPHONE_PUBLIC LinphoneVcard *linphone_factory_create_vcard(LinphoneFactory *factory);

241
/**
242 243
 * Create a #LinphoneVideoDefinition from a given width and height
 * @param[in] factory #LinphoneFactory singleton object
244 245
 * @param[in] width The width of the created video definition
 * @param[in] height The height of the created video definition
246
 * @return A new #LinphoneVideoDefinition object
247 248 249 250
 */
LINPHONE_PUBLIC LinphoneVideoDefinition * linphone_factory_create_video_definition(const LinphoneFactory *factory, unsigned int width, unsigned int height);

/**
251 252
 * Create a #LinphoneVideoDefinition from a given standard definition name
 * @param[in] factory #LinphoneFactory singleton object
253
 * @param[in] name The standard definition name of the video definition to create
254
 * @return A new #LinphoneVideoDefinition object
255 256 257 258 259
 */
LINPHONE_PUBLIC LinphoneVideoDefinition * linphone_factory_create_video_definition_from_name(const LinphoneFactory *factory, const char *name);

/**
 * Get the list of standard video definitions supported by Linphone.
260
 * @param[in] factory #LinphoneFactory singleton object
261 262 263 264
 * @return \bctbx_list{LinphoneVideoDefinition}
 */
LINPHONE_PUBLIC const bctbx_list_t * linphone_factory_get_supported_video_definitions(const LinphoneFactory *factory);

265 266
/**
 * Get the top directory where the resources are located.
267
 * @param[in] factory #LinphoneFactory object
268 269
 * @return The path to the top directory where the resources are located
 */
270
LINPHONE_PUBLIC const char * linphone_factory_get_top_resources_dir(const LinphoneFactory *factory);
271 272 273 274

/**
 * Set the top directory where the resources are located.
 * If you only define this top directory, the other resources directory will automatically be derived form this one.
275
 * @param[in] factory #LinphoneFactory object
276 277 278 279 280 281
 * @param[in] path The path to the top directory where the resources are located
 */
LINPHONE_PUBLIC void linphone_factory_set_top_resources_dir(LinphoneFactory *factory, const char *path);

/**
 * Get the directory where the data resources are located.
282
 * @param[in] factory #LinphoneFactory object
283 284
 * @return The path to the directory where the data resources are located
 */
285
LINPHONE_PUBLIC const char * linphone_factory_get_data_resources_dir(LinphoneFactory *factory);
286 287 288

/**
 * Set the directory where the data resources are located.
289
 * @param[in] factory #LinphoneFactory object
290 291 292 293 294 295
 * @param[in] path The path where the data resources are located
 */
LINPHONE_PUBLIC void linphone_factory_set_data_resources_dir(LinphoneFactory *factory, const char *path);

/**
 * Get the directory where the sound resources are located.
296
 * @param[in] factory #LinphoneFactory object
297 298
 * @return The path to the directory where the sound resources are located
 */
299
LINPHONE_PUBLIC const char * linphone_factory_get_sound_resources_dir(LinphoneFactory *factory);
300 301 302

/**
 * Set the directory where the sound resources are located.
303
 * @param[in] factory #LinphoneFactory object
304 305 306 307 308 309
 * @param[in] path The path where the sound resources are located
 */
LINPHONE_PUBLIC void linphone_factory_set_sound_resources_dir(LinphoneFactory *factory, const char *path);

/**
 * Get the directory where the ring resources are located.
310
 * @param[in] factory #LinphoneFactory object
311 312
 * @return The path to the directory where the ring resources are located
 */
313
LINPHONE_PUBLIC const char * linphone_factory_get_ring_resources_dir(LinphoneFactory *factory);
314 315 316

/**
 * Set the directory where the ring resources are located.
317
 * @param[in] factory #LinphoneFactory object
318 319 320 321 322 323
 * @param[in] path The path where the ring resources are located
 */
LINPHONE_PUBLIC void linphone_factory_set_ring_resources_dir(LinphoneFactory *factory, const char *path);

/**
 * Get the directory where the image resources are located.
324
 * @param[in] factory #LinphoneFactory object
325 326
 * @return The path to the directory where the image resources are located
 */
327
LINPHONE_PUBLIC const char * linphone_factory_get_image_resources_dir(LinphoneFactory *factory);
328 329 330

/**
 * Set the directory where the image resources are located.
331
 * @param[in] factory #LinphoneFactory object
332 333 334 335 336 337
 * @param[in] path The path where the image resources are located
 */
LINPHONE_PUBLIC void linphone_factory_set_image_resources_dir(LinphoneFactory *factory, const char *path);

/**
 * Get the directory where the mediastreamer2 plugins are located.
338
 * @param[in] factory #LinphoneFactory object
339 340
 * @return The path to the directory where the mediastreamer2 plugins are located, or NULL if it has not been set
 */
341
LINPHONE_PUBLIC const char * linphone_factory_get_msplugins_dir(LinphoneFactory *factory);
342 343 344

/**
 * Set the directory where the mediastreamer2 plugins are located.
345
 * @param[in] factory #LinphoneFactory object
346 347 348 349
 * @param[in] path The path to the directory where the mediastreamer2 plugins are located
 */
LINPHONE_PUBLIC void linphone_factory_set_msplugins_dir(LinphoneFactory *factory, const char *path);

350 351
/**
 * Creates an object LinphoneErrorInfo.
352 353
 * @param[in] factory #LinphoneFactory object
 * @return  #LinphoneErrorInfo object.
354
 */
355
LINPHONE_PUBLIC  LinphoneErrorInfo *linphone_factory_create_error_info(LinphoneFactory *factory);
356 357 358

/**
 * Creates an object LinphoneRange.
359 360
 * @param[in] factory #LinphoneFactory object
 * @return  #LinphoneRange object.
361 362
 */
LINPHONE_PUBLIC LinphoneRange *linphone_factory_create_range(LinphoneFactory *factory);
363 364 365

/**
 * Creates an object LinphoneTransports.
366 367
 * @param[in] factory #LinphoneFactory object
 * @return  #LinphoneTransports object.
368 369 370 371 372
 */
LINPHONE_PUBLIC LinphoneTransports *linphone_factory_create_transports(LinphoneFactory *factory);

/**
 * Creates an object LinphoneVideoActivationPolicy.
373 374
 * @param[in] factory #LinphoneFactory object
 * @return  #LinphoneVideoActivationPolicy object.
375 376
 */
LINPHONE_PUBLIC LinphoneVideoActivationPolicy *linphone_factory_create_video_activation_policy(LinphoneFactory *factory);
377

378 379
/**
 * Returns a bctbx_list_t of all DialPlans
380
 * @param[in] factory the #LinphoneFactory object
381 382 383 384
 * @return \bctbx_list{LinphoneDialPlan} a list of DialPlan
 */
LINPHONE_PUBLIC const bctbx_list_t * linphone_factory_get_dial_plans(const LinphoneFactory *factory);

385
/**
386 387 388
 * Creates an object #LinphoneContent
 * @param[in] factory the #LinphoneFactory
 * @return a #LinphoneContent
389 390 391 392
 */
LINPHONE_PUBLIC LinphoneContent *linphone_factory_create_content(LinphoneFactory *factory);

/**
393 394 395
 * Creates an object #LinphoneBuffer
 * @param[in] factory the #LinphoneFactory
 * @return a #LinphoneBuffer
396 397 398 399
 */
LINPHONE_PUBLIC LinphoneBuffer *linphone_factory_create_buffer(LinphoneFactory *factory);

/**
400 401
 * Creates an object #LinphoneBuffer
 * @param[in] factory the #LinphoneFactory
402 403
 * @param[in] data the data to set in the buffer
 * @param[in] size the size of the data
404
 * @return a #LinphoneBuffer
405 406 407 408
 */
LINPHONE_PUBLIC LinphoneBuffer *linphone_factory_create_buffer_from_data(LinphoneFactory *factory, const uint8_t *data, size_t size);

/**
409 410
 * Creates an object #LinphoneBuffer
 * @param[in] factory the #LinphoneFactory
411
 * @param[in] data the data to set in the buffer
412
 * @return a #LinphoneBuffer
413 414 415 416
 */
LINPHONE_PUBLIC LinphoneBuffer *linphone_factory_create_buffer_from_string(LinphoneFactory *factory, const char *data);

/**
417 418
 * Creates an object #LinphoneConfig
 * @param[in] factory the #LinphoneFactory
419
 * @param[in] path the path of the config
420
 * @return a #LinphoneConfig
421 422 423 424
 */
LINPHONE_PUBLIC LinphoneConfig *linphone_factory_create_config(LinphoneFactory *factory, const char *path);

/**
425 426
 * Creates an object #LinphoneConfig
 * @param[in] factory the #LinphoneFactory
427 428
 * @param[in] path the path of the config
 * @param[in] path the path of the factory
429
 * @return a #LinphoneConfig
430 431 432 433
 */
LINPHONE_PUBLIC LinphoneConfig *linphone_factory_create_config_with_factory(LinphoneFactory *factory, const char *path, const char *factory_path);

/**
434 435
 * Creates an object #LinphoneConfig
 * @param[in] factory the #LinphoneFactory
436
 * @param[in] data the config data
437
 * @return a #LinphoneConfig
438 439 440
 */
LINPHONE_PUBLIC LinphoneConfig *linphone_factory_create_config_from_string(LinphoneFactory *factory, const char *data);

441
/**
442 443
 * Gets the user data in the #LinphoneFactory object
 * @param[in] factory the #LinphoneFactory
444 445 446 447 448
 * @return the user data
*/
LINPHONE_PUBLIC void *linphone_factory_get_user_data(const LinphoneFactory *factory);

/**
449 450
 * Sets the user data in the #LinphoneFactory object
 * @param[in] factory the #LinphoneFactory object
451 452 453 454
 * @param[in] data the user data
*/
LINPHONE_PUBLIC void linphone_factory_set_user_data(LinphoneFactory *factory, void *data);

455 456
/**
 * Sets the log collection path
457
 * @param[in] factory the #LinphoneFactory
458
 * @param[in] path the path of the logs
459
 */
460
LINPHONE_PUBLIC void linphone_factory_set_log_collection_path(LinphoneFactory *factory, const char *path);
461 462 463

/**
 * Enables or disables log collection
464
 * @param[in] factory the #LinphoneFactory
465
 * @param[in] state the policy for log collection
466 467 468
 */
LINPHONE_PUBLIC void linphone_factory_enable_log_collection(LinphoneFactory *factory, LinphoneLogCollectionState state);

469 470 471 472 473 474 475
/**
 * Creates an object #LinphoneTunnelConfig
 * @param[in] factory the #LinphoneFactory
 * @return a #LinphoneTunnelConfig
 */
LINPHONE_PUBLIC LinphoneTunnelConfig *linphone_factory_create_tunnel_config(LinphoneFactory *factory);

476 477 478 479
/**
 * @}
 */

480
#ifdef __cplusplus
481 482 483 484 485
}
#endif


#endif // LINPHONE_FACTORY_H