1/* Copyright (C) 2008 The Android Open Source Project
2**
3** This software is licensed under the terms of the GNU General Public
4** License version 2, as published by the Free Software Foundation, and
5** may be copied, distributed, and modified under those terms.
6**
7** This program is distributed in the hope that it will be useful,
8** but WITHOUT ANY WARRANTY; without even the implied warranty of
9** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10** GNU General Public License for more details.
11*/
12#ifndef _ANDROID_UTILS_INI_H
13#define _ANDROID_UTILS_INI_H
14
15#include <stdint.h>
16
17#include "android/utils/compiler.h"
18
19ANDROID_BEGIN_HEADER
20
21/* the emulator supports a simple .ini file format for its configuration
22 * files. See docs/ANDROID-CONFIG-FILES.TXT for details.
23 */
24
25/* an opaque structure used to model an .ini configuration file */
26typedef struct IniFile   IniFile;
27
28/* creates a new IniFile object from a config file loaded in memory.
29 *  'fileName' is only used when writing a warning to stderr in case
30 * of badly formed output
31 */
32IniFile*  iniFile_newFromMemory( const char*  text, const char*  fileName  );
33
34/* creates a new IniFile object from a file path,
35 * returns NULL if the file cannot be opened.
36 */
37IniFile*  iniFile_newFromFile( const char*  filePath);
38
39/* try to write an IniFile into a given file.
40 * returns 0 on success, -1 on error (see errno for error code)
41 */
42int       iniFile_saveToFile( IniFile*  f, const char*  filePath );
43
44/* try to write an IniFile into a given file, ignorig pairs with empty values.
45 * returns 0 on success, -1 on error (see errno for error code)
46 */
47int       iniFile_saveToFileClean( IniFile*  f, const char*  filepath );
48
49/* free an IniFile object */
50void      iniFile_free( IniFile*  f );
51
52/* returns the number of (key.value) pairs in an IniFile */
53int       iniFile_getPairCount( IniFile*  f );
54
55/* returns the value of a given key from an IniFile.
56 * NULL if the key is not assigned in the corresponding configuration file
57 */
58const char*  iniFile_getValue( IniFile*  f, const char*  key );
59
60/* Copies a 'key, value' pair for an entry in the file.
61 * Param:
62 *  f - Initialized IniFile instance.
63 *  index - Index of the entry to copy. Must be less than value returned from the
64 *      iniFile_getPairCount routine.
65 *  key, value - Receives key, and value strings for the entry. If this routine
66 *      succeeds, the caller must free the buffers allocated for the strings.
67 * Return:
68 *  0 on success, -1 if the index exceeds the capacity of the file
69 */
70int     iniFile_getEntry(IniFile* f, int index, char** key, char** value);
71
72/* returns a copy of the value of a given key, or NULL if defaultValue is NULL.
73 * caller must free() it.
74 */
75char*   iniFile_getString( IniFile*  f, const char*  key, const char* defaultValue );
76
77/* returns an integer value, or a default in case the value string is
78 * missing or badly formatted
79 */
80int     iniFile_getInteger( IniFile*  f, const char*  key, int  defaultValue );
81
82/* returns a 64-bit integer value, or a default in case the value string is
83 * missing or badly formatted
84 */
85int64_t iniFile_getInt64( IniFile*  f, const char*  key, int64_t  defaultValue );
86
87/* returns a double value, or a default in case the value string is
88 * missing or badly formatted
89 */
90double  iniFile_getDouble( IniFile*  f, const char*  key, double  defaultValue );
91
92/* parses a key value as a boolean. Accepted values are "1", "0", "yes", "YES",
93 * "no" and "NO". Returns either 1 or 0.
94 * note that the default value must be provided as a string too
95 */
96int     iniFile_getBoolean( IniFile*  f, const char*  key, const char*  defaultValue );
97
98/* parses a key value as a disk size. this means it can be an integer followed
99 * by a suffix that can be one of "mMkKgG" which correspond to KiB, MiB and GiB
100 * multipliers.
101 *
102 * NOTE: we consider that 1K = 1024, not 1000.
103 */
104int64_t  iniFile_getDiskSize( IniFile*  f, const char*  key, const char*  defaultValue );
105
106/* These functions are used to set values in an IniFile */
107void iniFile_setValue( IniFile* f, const char* key, const char* value );
108void iniFile_setInteger( IniFile* f, const char* key, int value );
109void iniFile_setInt64( IniFile* f, const char* key, int64_t value );
110void iniFile_setDouble( IniFile* f, const char* key, double value );
111void iniFile_setBoolean( IniFile* f, const char* key, int value );
112void iniFile_setDiskSize( IniFile* f, const char* key, int64_t size );
113
114ANDROID_END_HEADER
115
116#endif /* _ANDROID_UTILS_INI_H */
117