1 /* 2 * Copyright 2015 Rockchip Electronics Co. LTD 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /*-------------------------------------------------------------------------*/ 18 /** 19 @file iniparser.h 20 @author N. Devillard 21 @brief Parser for ini files. 22 */ 23 /*--------------------------------------------------------------------------*/ 24 25 #ifndef _INIPARSER_H_ 26 #define _INIPARSER_H_ 27 28 /*--------------------------------------------------------------------------- 29 Includes 30 ---------------------------------------------------------------------------*/ 31 32 #include <stdio.h> 33 #include <stdlib.h> 34 #include <string.h> 35 36 /* 37 * The following #include is necessary on many Unixes but not Linux. 38 * It is not needed for Windows platforms. 39 * Uncomment it if needed. 40 */ 41 /* #include <unistd.h> */ 42 43 #include "dictionary.h" 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /*-------------------------------------------------------------------------*/ 50 /** 51 @brief Configure a function to receive the error messages. 52 @param errback Function to call. 53 54 By default, the error will be printed on stderr. If a null pointer is passed 55 as errback the error callback will be switched back to default. 56 */ 57 /*--------------------------------------------------------------------------*/ 58 59 void iniparser_set_error_callback(int (*errback)(const char *, ...)); 60 61 /*-------------------------------------------------------------------------*/ 62 /** 63 @brief Get number of sections in a dictionary 64 @param d Dictionary to examine 65 @return int Number of sections found in dictionary 66 67 This function returns the number of sections found in a dictionary. 68 The test to recognize sections is done on the string stored in the 69 dictionary: a section name is given as "section" whereas a key is 70 stored as "section:key", thus the test looks for entries that do not 71 contain a colon. 72 73 This clearly fails in the case a section name contains a colon, but 74 this should simply be avoided. 75 76 This function returns -1 in case of error. 77 */ 78 /*--------------------------------------------------------------------------*/ 79 80 int iniparser_getnsec(const dictionary * d); 81 82 83 /*-------------------------------------------------------------------------*/ 84 /** 85 @brief Get name for section n in a dictionary. 86 @param d Dictionary to examine 87 @param n Section number (from 0 to nsec-1). 88 @return Pointer to char string 89 90 This function locates the n-th section in a dictionary and returns 91 its name as a pointer to a string statically allocated inside the 92 dictionary. Do not free or modify the returned string! 93 94 This function returns NULL in case of error. 95 */ 96 /*--------------------------------------------------------------------------*/ 97 98 const char * iniparser_getsecname(const dictionary * d, int n); 99 100 101 /*-------------------------------------------------------------------------*/ 102 /** 103 @brief Save a dictionary to a loadable ini file 104 @param d Dictionary to dump 105 @param f Opened file pointer to dump to 106 @return void 107 108 This function dumps a given dictionary into a loadable ini file. 109 It is Ok to specify @c stderr or @c stdout as output files. 110 */ 111 /*--------------------------------------------------------------------------*/ 112 113 void iniparser_dump_ini(const dictionary * d, FILE * f); 114 115 /*-------------------------------------------------------------------------*/ 116 /** 117 @brief Save a dictionary section to a loadable ini file 118 @param d Dictionary to dump 119 @param s Section name of dictionary to dump 120 @param f Opened file pointer to dump to 121 @return void 122 123 This function dumps a given section of a given dictionary into a loadable ini 124 file. It is Ok to specify @c stderr or @c stdout as output files. 125 */ 126 /*--------------------------------------------------------------------------*/ 127 128 void iniparser_dumpsection_ini(const dictionary * d, const char * s, FILE * f); 129 130 /*-------------------------------------------------------------------------*/ 131 /** 132 @brief Dump a dictionary to an opened file pointer. 133 @param d Dictionary to dump. 134 @param f Opened file pointer to dump to. 135 @return void 136 137 This function prints out the contents of a dictionary, one element by 138 line, onto the provided file pointer. It is OK to specify @c stderr 139 or @c stdout as output files. This function is meant for debugging 140 purposes mostly. 141 */ 142 /*--------------------------------------------------------------------------*/ 143 void iniparser_dump(const dictionary * d, FILE * f); 144 145 /*-------------------------------------------------------------------------*/ 146 /** 147 @brief Get the number of keys in a section of a dictionary. 148 @param d Dictionary to examine 149 @param s Section name of dictionary to examine 150 @return Number of keys in section 151 */ 152 /*--------------------------------------------------------------------------*/ 153 int iniparser_getsecnkeys(const dictionary * d, const char * s); 154 155 /*-------------------------------------------------------------------------*/ 156 /** 157 @brief Get the number of keys in a section of a dictionary. 158 @param d Dictionary to examine 159 @param s Section name of dictionary to examine 160 @param keys Already allocated array to store the keys in 161 @return The pointer passed as `keys` argument or NULL in case of error 162 163 This function queries a dictionary and finds all keys in a given section. 164 The keys argument should be an array of pointers which size has been 165 determined by calling `iniparser_getsecnkeys` function prior to this one. 166 167 Each pointer in the returned char pointer-to-pointer is pointing to 168 a string allocated in the dictionary; do not free or modify them. 169 */ 170 /*--------------------------------------------------------------------------*/ 171 const char ** iniparser_getseckeys(const dictionary * d, const char * s, const char ** keys); 172 173 174 /*-------------------------------------------------------------------------*/ 175 /** 176 @brief Get the string associated to a key 177 @param d Dictionary to search 178 @param key Key string to look for 179 @param def Default value to return if key not found. 180 @return pointer to statically allocated character string 181 182 This function queries a dictionary for a key. A key as read from an 183 ini file is given as "section:key". If the key cannot be found, 184 the pointer passed as 'def' is returned. 185 The returned char pointer is pointing to a string allocated in 186 the dictionary, do not free or modify it. 187 */ 188 /*--------------------------------------------------------------------------*/ 189 const char * iniparser_getstring(const dictionary * d, const char * key, const char * def); 190 191 /*-------------------------------------------------------------------------*/ 192 /** 193 @brief Get the string associated to a key, convert to an int 194 @param d Dictionary to search 195 @param key Key string to look for 196 @param notfound Value to return in case of error 197 @return integer 198 199 This function queries a dictionary for a key. A key as read from an 200 ini file is given as "section:key". If the key cannot be found, 201 the notfound value is returned. 202 203 Supported values for integers include the usual C notation 204 so decimal, octal (starting with 0) and hexadecimal (starting with 0x) 205 are supported. Examples: 206 207 - "42" -> 42 208 - "042" -> 34 (octal -> decimal) 209 - "0x42" -> 66 (hexa -> decimal) 210 211 Warning: the conversion may overflow in various ways. Conversion is 212 totally outsourced to strtol(), see the associated man page for overflow 213 handling. 214 215 Credits: Thanks to A. Becker for suggesting strtol() 216 */ 217 /*--------------------------------------------------------------------------*/ 218 int iniparser_getint(const dictionary * d, const char * key, int notfound); 219 220 /*-------------------------------------------------------------------------*/ 221 /** 222 @brief Get the string associated to a key, convert to an long int 223 @param d Dictionary to search 224 @param key Key string to look for 225 @param notfound Value to return in case of error 226 @return integer 227 228 This function queries a dictionary for a key. A key as read from an 229 ini file is given as "section:key". If the key cannot be found, 230 the notfound value is returned. 231 232 Supported values for integers include the usual C notation 233 so decimal, octal (starting with 0) and hexadecimal (starting with 0x) 234 are supported. Examples: 235 236 - "42" -> 42 237 - "042" -> 34 (octal -> decimal) 238 - "0x42" -> 66 (hexa -> decimal) 239 240 Warning: the conversion may overflow in various ways. Conversion is 241 totally outsourced to strtol(), see the associated man page for overflow 242 handling. 243 */ 244 /*--------------------------------------------------------------------------*/ 245 long int iniparser_getlongint(const dictionary * d, const char * key, long int notfound); 246 247 248 /*-------------------------------------------------------------------------*/ 249 /** 250 @brief Get the string associated to a key, convert to a double 251 @param d Dictionary to search 252 @param key Key string to look for 253 @param notfound Value to return in case of error 254 @return double 255 256 This function queries a dictionary for a key. A key as read from an 257 ini file is given as "section:key". If the key cannot be found, 258 the notfound value is returned. 259 */ 260 /*--------------------------------------------------------------------------*/ 261 double iniparser_getdouble(const dictionary * d, const char * key, double notfound); 262 263 /*-------------------------------------------------------------------------*/ 264 /** 265 @brief Get the string associated to a key, convert to a boolean 266 @param d Dictionary to search 267 @param key Key string to look for 268 @param notfound Value to return in case of error 269 @return integer 270 271 This function queries a dictionary for a key. A key as read from an 272 ini file is given as "section:key". If the key cannot be found, 273 the notfound value is returned. 274 275 A true boolean is found if one of the following is matched: 276 277 - A string starting with 'y' 278 - A string starting with 'Y' 279 - A string starting with 't' 280 - A string starting with 'T' 281 - A string starting with '1' 282 283 A false boolean is found if one of the following is matched: 284 285 - A string starting with 'n' 286 - A string starting with 'N' 287 - A string starting with 'f' 288 - A string starting with 'F' 289 - A string starting with '0' 290 291 The notfound value returned if no boolean is identified, does not 292 necessarily have to be 0 or 1. 293 */ 294 /*--------------------------------------------------------------------------*/ 295 int iniparser_getboolean(const dictionary * d, const char * key, int notfound); 296 297 298 /*-------------------------------------------------------------------------*/ 299 /** 300 @brief Set an entry in a dictionary. 301 @param ini Dictionary to modify. 302 @param entry Entry to modify (entry name) 303 @param val New value to associate to the entry. 304 @return int 0 if Ok, -1 otherwise. 305 306 If the given entry can be found in the dictionary, it is modified to 307 contain the provided value. If it cannot be found, the entry is created. 308 It is Ok to set val to NULL. 309 */ 310 /*--------------------------------------------------------------------------*/ 311 int iniparser_set(dictionary * ini, const char * entry, const char * val); 312 313 314 /*-------------------------------------------------------------------------*/ 315 /** 316 @brief Delete an entry in a dictionary 317 @param ini Dictionary to modify 318 @param entry Entry to delete (entry name) 319 @return void 320 321 If the given entry can be found, it is deleted from the dictionary. 322 */ 323 /*--------------------------------------------------------------------------*/ 324 void iniparser_unset(dictionary * ini, const char * entry); 325 326 /*-------------------------------------------------------------------------*/ 327 /** 328 @brief Finds out if a given entry exists in a dictionary 329 @param ini Dictionary to search 330 @param entry Name of the entry to look for 331 @return integer 1 if entry exists, 0 otherwise 332 333 Finds out if a given entry exists in the dictionary. Since sections 334 are stored as keys with NULL associated values, this is the only way 335 of querying for the presence of sections in a dictionary. 336 */ 337 /*--------------------------------------------------------------------------*/ 338 int iniparser_find_entry(const dictionary * ini, const char * entry) ; 339 340 /*-------------------------------------------------------------------------*/ 341 /** 342 @brief Parse an ini file and return an allocated dictionary object 343 @param ininame Name of the ini file to read. 344 @return Pointer to newly allocated dictionary 345 346 This is the parser for ini files. This function is called, providing 347 the name of the file to be read. It returns a dictionary object that 348 should not be accessed directly, but through accessor functions 349 instead. 350 351 The returned dictionary must be freed using iniparser_freedict(). 352 */ 353 /*--------------------------------------------------------------------------*/ 354 dictionary * iniparser_load(const char * ininame); 355 356 /*-------------------------------------------------------------------------*/ 357 /** 358 @brief Free all memory associated to an ini dictionary 359 @param d Dictionary to free 360 @return void 361 362 Free all memory associated to an ini dictionary. 363 It is mandatory to call this function before the dictionary object 364 gets out of the current context. 365 */ 366 /*--------------------------------------------------------------------------*/ 367 void iniparser_freedict(dictionary * d); 368 369 #ifdef __cplusplus 370 } 371 #endif 372 373 #endif 374