lpconfig.h 19.5 KB
Newer Older
aymeric's avatar
aymeric committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
/***************************************************************************
 *            lpconfig.h
 *
 *  Thu Mar 10 15:02:49 2005
 *  Copyright  2005  Simon Morlat
 *  Email simon.morlat@linphone.org
 ****************************************************************************/

/*
 *  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 Library General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */
24

aymeric's avatar
aymeric committed
25 26
#ifndef LPCONFIG_H
#define LPCONFIG_H
27

28
#include "linphone/types.h"
Yann Diorcet's avatar
Yann Diorcet committed
29

30 31 32 33 34
/**
 * @addtogroup misc
 * @{
 */

35
/**
36
 * Safely downcast a belle_sip_object into #LinphoneConfig
37 38 39
 */
#define LINPHONE_CONFIG(obj) BELLE_SIP_CAST(obj, LinphoneConfig);

aymeric's avatar
aymeric committed
40 41 42 43
#ifdef __cplusplus
extern "C" {
#endif

44
/**
45
 * Instantiates a #LinphoneConfig object from a user config file.
46 47
 * The caller of this constructor owns a reference. linphone_config_unref() must be called when this object is no longer needed.
 * @ingroup misc
48
 * @param filename the filename of the config file to read to fill the instantiated #LinphoneConfig
49
 * @see linphone_config_new_with_factory
50
 */
51
LINPHONE_PUBLIC LinphoneConfig * linphone_config_new(const char *filename);
52

53
/**
54
 * Instantiates a #LinphoneConfig object from a user provided buffer.
55 56
 * The caller of this constructor owns a reference. linphone_config_unref() must be called when this object is no longer needed.
 * @ingroup misc
57
 * @param buffer the buffer from which the #LinphoneConfig will be retrieved. We expect the buffer to be null-terminated.
58 59
 * @see linphone_config_new_with_factory
 * @see linphone_config_new
60
 */
61
LINPHONE_PUBLIC LinphoneConfig * linphone_config_new_from_buffer(const char *buffer);
62

63
/**
64
 * Instantiates a #LinphoneConfig object from a user config file and a factory config file.
65 66
 * The caller of this constructor owns a reference. linphone_config_unref() must be called when this object is no longer needed.
 * @ingroup misc
67 68
 * @param config_filename the filename of the user config file to read to fill the instantiated #LinphoneConfig
 * @param factory_config_filename the filename of the factory config file to read to fill the instantiated #LinphoneConfig
69
 * @see linphone_config_new
70
 *
71
 * The user config file is read first to fill the #LinphoneConfig and then the factory config file is read.
72 73 74
 * Therefore the configuration parameters defined in the user config file will be overwritten by the parameters
 * defined in the factory config file.
 */
75
LINPHONE_PUBLIC LinphoneConfig * linphone_config_new_with_factory(const char *config_filename, const char *factory_config_filename);
76

77
/**
78
 * Reads a user config file and fill the #LinphoneConfig with the read config values.
79
 * @ingroup misc
80 81
 * @param lpconfig The #LinphoneConfig object to fill with the content of the file
 * @param filename The filename of the config file to read to fill the #LinphoneConfig
82
 */
83
LINPHONE_PUBLIC LinphoneStatus linphone_config_read_file(LinphoneConfig *lpconfig, const char *filename);
84

85
/**
86
 * Reads a xml config file and fill the #LinphoneConfig with the read config dynamic values.
87
 * @ingroup misc
88 89
 * @param lpconfig The #LinphoneConfig object to fill with the content of the file
 * @param filename The filename of the config file to read to fill the #LinphoneConfig
90
 */
91
LINPHONE_PUBLIC const char* linphone_config_load_from_xml_file(LinphoneConfig *lpc, const char *filename);
92

Erwan Croze's avatar
Erwan Croze committed
93
/**
94
 * Reads a xml config string and fill the #LinphoneConfig with the read config dynamic values.
Erwan Croze's avatar
Erwan Croze committed
95
 * @ingroup misc
96 97
 * @param lpconfig The #LinphoneConfig object to fill with the content of the file
 * @param buffer The string of the config file to fill the #LinphoneConfig
98
 * @return 0 in case of success
Erwan Croze's avatar
Erwan Croze committed
99
 */
100
LINPHONE_PUBLIC LinphoneStatus linphone_config_load_from_xml_string(LpConfig *lpc, const char *buffer);
Erwan Croze's avatar
Erwan Croze committed
101

smorlat's avatar
smorlat committed
102 103
/**
 * Retrieves a configuration item as a string, given its section, key, and default value.
104
 *
smorlat's avatar
smorlat committed
105 106
 * The default value string is returned if the config item isn't found.
**/
107
LINPHONE_PUBLIC const char *linphone_config_get_string(const LinphoneConfig *lpconfig, const char *section, const char *key, const char *default_string);
108

109 110
/**
 * Retrieves a configuration item as a list of strings, given its section, key, and default value.
Ghislain MARY's avatar
Ghislain MARY committed
111
 * The default value is returned if the config item is not found.
112
 * @param[in] lpconfig A #LinphoneConfig object
Ghislain MARY's avatar
Ghislain MARY committed
113 114
 * @param[in] section The section from which to retrieve a configuration item
 * @param[in] key The name of the configuration item to retrieve
115 116
 * @param[in] default_list \bctbx_list{const char *}
 * @return \bctbx_list{const char *}
117
 */
118
LINPHONE_PUBLIC bctbx_list_t * linphone_config_get_string_list(const LinphoneConfig *lpconfig, const char *section, const char *key, bctbx_list_t *default_list);
119

120 121 122 123 124 125
/**
 * Retrieves a configuration item as a range, given its section, key, and default min and max values.
 *
 * @return TRUE if the value is successfully parsed as a range, FALSE otherwise.
 * If FALSE is returned, min and max are filled respectively with default_min and default_max values.
 */
126
LINPHONE_PUBLIC bool_t linphone_config_get_range(const LinphoneConfig *lpconfig, const char *section, const char *key, int *min, int *max, int default_min, int default_max);
127

smorlat's avatar
smorlat committed
128 129
/**
 * Retrieves a configuration item as an integer, given its section, key, and default value.
130
 *
smorlat's avatar
smorlat committed
131 132
 * The default integer value is returned if the config item isn't found.
**/
133
LINPHONE_PUBLIC int linphone_config_get_int(const LinphoneConfig *lpconfig,const char *section, const char *key, int default_value);
134

135 136 137 138 139 140 141
/**
 * Retrieves a configuration item as a boolean, given its section, key, and default value.
 *
 * The default boolean value is returned if the config item isn't found.
**/
LINPHONE_PUBLIC bool_t linphone_config_get_bool(const LpConfig *lpconfig, const char *section, const char *key, bool_t default_value);

142 143
/**
 * Retrieves a configuration item as a 64 bit integer, given its section, key, and default value.
144
 *
145 146
 * The default integer value is returned if the config item isn't found.
**/
147
LINPHONE_PUBLIC int64_t linphone_config_get_int64(const LinphoneConfig *lpconfig,const char *section, const char *key, int64_t default_value);
148

smorlat's avatar
smorlat committed
149 150
/**
 * Retrieves a configuration item as a float, given its section, key, and default value.
151
 *
smorlat's avatar
smorlat committed
152 153
 * The default float value is returned if the config item isn't found.
**/
154
LINPHONE_PUBLIC float linphone_config_get_float(const LinphoneConfig *lpconfig,const char *section, const char *key, float default_value);
155

smorlat's avatar
smorlat committed
156
/**
157
 * Sets a string config item
smorlat's avatar
smorlat committed
158
**/
159
LINPHONE_PUBLIC void linphone_config_set_string(LinphoneConfig *lpconfig,const char *section, const char *key, const char *value);
160

161 162
/**
 * Sets a string list config item
163
 * @param[in] lpconfig A #LinphoneConfig object
Ghislain MARY's avatar
Ghislain MARY committed
164 165
 * @param[in] section The name of the section to put the configuration item into
 * @param[in] key The name of the configuration item to set
166
 * @param[in] value \bctbx_list{const char *} The value to set
167
 */
168
LINPHONE_PUBLIC void linphone_config_set_string_list(LinphoneConfig *lpconfig, const char *section, const char *key, const bctbx_list_t *value);
169

170 171 172
/**
 * Sets a range config item
 */
173
LINPHONE_PUBLIC void linphone_config_set_range(LinphoneConfig *lpconfig, const char *section, const char *key, int min_value, int max_value);
174

smorlat's avatar
smorlat committed
175 176 177
/**
 * Sets an integer config item
**/
178
LINPHONE_PUBLIC void linphone_config_set_int(LinphoneConfig *lpconfig,const char *section, const char *key, int value);
179

180 181 182 183 184
/**
 * Sets a boolean config item
**/
LINPHONE_PUBLIC void linphone_config_set_bool(LinphoneConfig *lpconfig,const char *section, const char *key, bool_t value);

185 186 187
/**
 * Sets an integer config item, but store it as hexadecimal
**/
188
LINPHONE_PUBLIC void linphone_config_set_int_hex(LinphoneConfig *lpconfig,const char *section, const char *key, int value);
189

190 191 192
/**
 * Sets a 64 bits integer config item
**/
193
LINPHONE_PUBLIC void linphone_config_set_int64(LinphoneConfig *lpconfig,const char *section, const char *key, int64_t value);
194

195 196 197
/**
 * Sets a float config item
**/
198
LINPHONE_PUBLIC void linphone_config_set_float(LinphoneConfig *lpconfig,const char *section, const char *key, float value);
199

smorlat's avatar
smorlat committed
200 201 202
/**
 * Writes the config file to disk.
**/
203
LINPHONE_PUBLIC LinphoneStatus linphone_config_sync(LinphoneConfig *lpconfig);
204

smorlat's avatar
smorlat committed
205 206 207
/**
 * Returns 1 if a given section is present in the configuration.
**/
208
LINPHONE_PUBLIC int linphone_config_has_section(const LinphoneConfig *lpconfig, const char *section);
209

smorlat's avatar
smorlat committed
210 211 212
/**
 * Removes every pair of key,value in a section and remove the section.
**/
213
LINPHONE_PUBLIC void linphone_config_clean_section(LinphoneConfig *lpconfig, const char *section);
214

jehan's avatar
jehan committed
215 216
/**
 * Returns 1 if a given section  with a given key is present in the configuration.
217
 * @param[in] lpconfig The #LinphoneConfig object
jehan's avatar
jehan committed
218 219 220
 * @param[in] section
 * @param[in] key
 **/
221
LINPHONE_PUBLIC int linphone_config_has_entry(const LinphoneConfig *lpconfig, const char *section, const char *key);
jehan's avatar
jehan committed
222 223 224

/**
 * Removes entries for key,value in a section.
225
 * @param[in] lpconfig The #LinphoneConfig object
jehan's avatar
jehan committed
226 227 228
 * @param[in] section
 * @param[in] key
 **/
229
LINPHONE_PUBLIC void linphone_config_clean_entry(LinphoneConfig *lpconfig, const char *section, const char *key);
230

231
/**
232
 * Returns the list of sections' names in the LinphoneConfig.
233
 * @param[in] lpconfig The #LinphoneConfig object
234
 * @return a null terminated static array of strings
235 236
 * @deprecated use linphone_config_get_sections_names_list instead
 * @donotwrap
237
**/
238
LINPHONE_PUBLIC const char** linphone_config_get_sections_names(LinphoneConfig *lpconfig);
239

240 241
/**
 * Returns the list of sections' names in the LinphoneConfig.
242
 * @param[in] lpconfig The #LinphoneConfig object
243 244 245 246
 * @return \bctbx_list{char *} a null terminated static array of strings
**/
LINPHONE_PUBLIC const bctbx_list_t * linphone_config_get_sections_names_list(LpConfig *lpconfig);

247
/**
248 249
 * @brief Call a function for each section present in the configuration.
 * @donotwrap
250
**/
251
void linphone_config_for_each_section(const LinphoneConfig *lpconfig, void (*callback)(const char *section, void *ctx), void *ctx);
252

253
/**
254 255
 * @brief Call a function for each entry present in a section configuration.
 * @donotwrap
256
**/
257
void linphone_config_for_each_entry(const LinphoneConfig *lpconfig, const char *section, void (*callback)(const char *entry, void *ctx), void *ctx);
258

259
/*tells whether uncommited (with linphone_config_sync()) modifications exist*/
260
bool_t linphone_config_needs_commit(const LinphoneConfig *lpconfig);
261

262
LINPHONE_PUBLIC void linphone_config_destroy(LinphoneConfig *cfg);
263 264 265 266 267

/**
 * Retrieves a default configuration item as an integer, given its section, key, and default value.
 * The default integer value is returned if the config item isn't found.
**/
268
LINPHONE_PUBLIC int linphone_config_get_default_int(const LinphoneConfig *lpconfig, const char *section, const char *key, int default_value);
269 270 271 272 273

/**
 * Retrieves a default configuration item as a 64 bit integer, given its section, key, and default value.
 * The default integer value is returned if the config item isn't found.
**/
274
LINPHONE_PUBLIC int64_t linphone_config_get_default_int64(const LinphoneConfig *lpconfig, const char *section, const char *key, int64_t default_value);
275 276 277 278 279

/**
 * Retrieves a default configuration item as a float, given its section, key, and default value.
 * The default float value is returned if the config item isn't found.
**/
280
LINPHONE_PUBLIC float linphone_config_get_default_float(const LinphoneConfig *lpconfig, const char *section, const char *key, float default_value);
281 282 283 284 285

/**
 * Retrieves a default configuration item as a string, given its section, key, and default value.
 * The default value string is returned if the config item isn't found.
**/
286
LINPHONE_PUBLIC const char* linphone_config_get_default_string(const LinphoneConfig *lpconfig, const char *section, const char *key, const char *default_value);
287 288 289 290 291

/**
 * Retrieves a section parameter item as a string, given its section and key.
 * The default value string is returned if the config item isn't found.
**/
292
LINPHONE_PUBLIC const char* linphone_config_get_section_param_string(const LinphoneConfig *lpconfig, const char *section, const char *key, const char *default_value);
293

294 295 296
/**
 * increment reference count
**/
297
LINPHONE_PUBLIC LinphoneConfig *linphone_config_ref(LinphoneConfig *lpconfig);
298 299 300 301

/**
 * Decrement reference count, which will eventually free the object.
**/
302
LINPHONE_PUBLIC void linphone_config_unref(LinphoneConfig *lpconfig);
303

304
/**
305
 * Write a string in a file placed relatively with the Linphone configuration file.
306
 * @param lpconfig #LinphoneConfig instance used as a reference
307 308 309
 * @param filename Name of the file where to write data. The name is relative to the place of the config file
 * @param data String to write
 */
310
LINPHONE_PUBLIC void linphone_config_write_relative_file(const LinphoneConfig *lpconfig, const char *filename, const char *data);
311 312

/**
313
 * Read a string from a file placed beside the Linphone configuration file
314
 * @param lpconfig #LinphoneConfig instance used as a reference
315
 * @param filename Name of the file where data will be read from. The name is relative to the place of the config file
316 317 318
 * @param data Buffer where read string will be stored
 * @param max_length Length of the buffer
 * @return 0 on success, -1 on failure
319
 * @donotwrap
320
 */
321
LINPHONE_PUBLIC LinphoneStatus linphone_config_read_relative_file(const LinphoneConfig *lpconfig, const char *filename, char *data, size_t max_length);
322

323 324 325
/**
 * @return TRUE if file exists relative to the to the current location
**/
326
LINPHONE_PUBLIC bool_t linphone_config_relative_file_exists(const LinphoneConfig *lpconfig, const char *filename);
327

328
/**
329 330
 * Dumps the #LinphoneConfig as XML into a buffer
 * @param[in] lpconfig The #LinphoneConfig object
331 332
 * @return The buffer that contains the XML dump
**/
333
LINPHONE_PUBLIC char* linphone_config_dump_as_xml(const LinphoneConfig *lpconfig);
334

335
/**
336 337
 * Dumps the #LinphoneConfig as INI into a buffer
 * @param[in] lpconfig The #LinphoneConfig object
338 339
 * @return The buffer that contains the config dump
**/
340
LINPHONE_PUBLIC char* linphone_config_dump(const LinphoneConfig *lpconfig);
341

342 343 344
/**
 * Retrieves the overwrite flag for a config item
**/
345
LINPHONE_PUBLIC bool_t linphone_config_get_overwrite_flag_for_entry(const LinphoneConfig *lpconfig, const char *section, const char *key);
346 347 348 349

/**
 * Sets the overwrite flag for a config item (used when dumping config as xml)
**/
350
LINPHONE_PUBLIC void linphone_config_set_overwrite_flag_for_entry(LinphoneConfig *lpconfig, const char *section, const char *key, bool_t value);
351

352 353 354
/**
 * Retrieves the overwrite flag for a config section
**/
355
LINPHONE_PUBLIC bool_t linphone_config_get_overwrite_flag_for_section(const LinphoneConfig *lpconfig, const char *section);
356 357 358 359

/**
 * Sets the overwrite flag for a config section (used when dumping config as xml)
**/
360
LINPHONE_PUBLIC void linphone_config_set_overwrite_flag_for_section(LinphoneConfig *lpconfig, const char *section, bool_t value);
361

362 363 364
/**
 * Retrieves the skip flag for a config item
**/
365
LINPHONE_PUBLIC bool_t linphone_config_get_skip_flag_for_entry(const LinphoneConfig *lpconfig, const char *section, const char *key);
366 367 368 369

/**
 * Sets the skip flag for a config item (used when dumping config as xml)
**/
370
LINPHONE_PUBLIC void linphone_config_set_skip_flag_for_entry(LinphoneConfig *lpconfig, const char *section, const char *key, bool_t value);
371 372 373 374

/**
 * Retrieves the skip flag for a config section
**/
375
LINPHONE_PUBLIC bool_t linphone_config_get_skip_flag_for_section(const LinphoneConfig *lpconfig, const char *section);
376 377 378 379

/**
 * Sets the skip flag for a config section (used when dumping config as xml)
**/
380
LINPHONE_PUBLIC void linphone_config_set_skip_flag_for_section(LinphoneConfig *lpconfig, const char *section, bool_t value);
381

382 383
/**
 * Converts a config section into a dictionary.
384
 * @return a dictionary with all the keys from a section, or NULL if the section doesn't exist
385 386 387 388 389 390 391 392 393
 */
LINPHONE_PUBLIC LinphoneDictionary * lp_config_section_to_dict( const LpConfig* lpconfig, const char* section );

/**
 * Loads a dictionary into a section of the lpconfig. If the section doesn't exist it is created.
 * Overwrites existing keys, creates non-existing keys.
 */
LINPHONE_PUBLIC void lp_config_load_dict_to_section( LpConfig* lpconfig, const char* section, const LinphoneDictionary* dict);

aymeric's avatar
aymeric committed
394 395 396 397
#ifdef __cplusplus
}
#endif

398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446
// Define old function names for backward compatibility
#define lp_config_new linphone_config_new
#define lp_config_new_from_buffer linphone_config_new_from_buffer
#define lp_config_new_with_factory linphone_config_new_with_factory
#define lp_config_read_file linphone_config_read_file
#define lp_config_get_string linphone_config_get_string
#define lp_config_get_string_list linphone_config_get_string_list
#define lp_config_get_range linphone_config_get_range
#define lp_config_get_int linphone_config_get_int
#define lp_config_get_int64 linphone_config_get_int64
#define lp_config_get_float linphone_config_get_float
#define lp_config_set_string linphone_config_set_string
#define lp_config_set_string_list linphone_config_set_string_list
#define lp_config_set_range linphone_config_set_range
#define lp_config_set_int linphone_config_set_int
#define lp_config_set_int_hex linphone_config_set_int_hex
#define lp_config_set_int64 linphone_config_set_int64
#define lp_config_set_float linphone_config_set_float
#define lp_config_sync linphone_config_sync
#define lp_config_has_section linphone_config_has_section
#define lp_config_clean_section linphone_config_clean_section
#define lp_config_has_entry linphone_config_has_entry
#define lp_config_clean_entry linphone_config_clean_entry
#define lp_config_get_sections_names linphone_config_get_sections_names
#define lp_config_for_each_section linphone_config_for_each_section
#define lp_config_for_each_entry linphone_config_for_each_entry
#define lp_config_needs_commit linphone_config_needs_commit
#define lp_config_destroy linphone_config_destroy
#define lp_config_get_default_int linphone_config_get_default_int
#define lp_config_get_default_int64 linphone_config_get_default_int64
#define lp_config_get_default_float linphone_config_get_default_float
#define lp_config_get_default_string linphone_config_get_default_string
#define lp_config_get_section_param_string linphone_config_get_section_param_string
#define lp_config_ref linphone_config_ref
#define lp_config_unref linphone_config_unref
#define lp_config_write_relative_file linphone_config_write_relative_file
#define lp_config_read_relative_file linphone_config_read_relative_file
#define lp_config_relative_file_exists linphone_config_relative_file_exists
#define lp_config_dump_as_xml linphone_config_dump_as_xml
#define lp_config_dump linphone_config_dump
#define lp_config_get_overwrite_flag_for_entry linphone_config_get_overwrite_flag_for_entry
#define lp_config_set_overwrite_flag_for_entry linphone_config_set_overwrite_flag_for_entry
#define lp_config_get_overwrite_flag_for_section linphone_config_get_overwrite_flag_for_section
#define lp_config_set_overwrite_flag_for_section linphone_config_set_overwrite_flag_for_section
#define lp_config_get_skip_flag_for_entry linphone_config_get_skip_flag_for_entry
#define lp_config_set_skip_flag_for_entry linphone_config_set_skip_flag_for_entry
#define lp_config_get_skip_flag_for_section linphone_config_get_skip_flag_for_section
#define lp_config_set_skip_flag_for_section linphone_config_set_skip_flag_for_section

447 448 449 450
/**
 * @}
 */

aymeric's avatar
aymeric committed
451
#endif