00001 00002 /*-------------------------------------------------------------------------*/ 00003 /** 00004 @file iniparser.h 00005 @author N. Devillard 00006 @date Mar 2000 00007 @version $Revision: 1.20 $ 00008 @brief Parser for ini files. 00009 */ 00010 /*--------------------------------------------------------------------------*/ 00011 00012 /* 00013 $Id: iniparser.h,v 1.20 2005/08/19 17:23:21 ndevilla Exp $ 00014 $Author: ndevilla $ 00015 $Date: 2005/08/19 17:23:21 $ 00016 $Revision: 1.20 $ 00017 */ 00018 00019 #ifndef _INIPARSER_H_ 00020 #define _INIPARSER_H_ 00021 00022 /*--------------------------------------------------------------------------- 00023 Includes 00024 ---------------------------------------------------------------------------*/ 00025 00026 #include <stdio.h> 00027 #include <stdlib.h> 00028 #include <string.h> 00029 00030 /* 00031 * The following #include is necessary on many Unixes but not Linux. 00032 * It is not needed for Windows platforms. 00033 * Uncomment it if needed. 00034 */ 00035 /* #include <unistd.h> */ 00036 00037 #include "dictionary.h" 00038 00039 /*-------------------------------------------------------------------------*/ 00040 /** 00041 @brief Get number of sections in a dictionary 00042 @param d Dictionary to examine 00043 @return int Number of sections found in dictionary 00044 00045 This function returns the number of sections found in a dictionary. 00046 The test to recognize sections is done on the string stored in the 00047 dictionary: a section name is given as "section" whereas a key is 00048 stored as "section:key", thus the test looks for entries that do not 00049 contain a colon. 00050 00051 This clearly fails in the case a section name contains a colon, but 00052 this should simply be avoided. 00053 00054 This function returns -1 in case of error. 00055 */ 00056 /*--------------------------------------------------------------------------*/ 00057 00058 int iniparser_getnsec(dictionary * d); 00059 00060 00061 /*-------------------------------------------------------------------------*/ 00062 /** 00063 @brief Get name for section n in a dictionary. 00064 @param d Dictionary to examine 00065 @param n Section number (from 0 to nsec-1). 00066 @return Pointer to char string 00067 00068 This function locates the n-th section in a dictionary and returns 00069 its name as a pointer to a string statically allocated inside the 00070 dictionary. Do not free or modify the returned string! 00071 00072 This function returns NULL in case of error. 00073 */ 00074 /*--------------------------------------------------------------------------*/ 00075 00076 char * iniparser_getsecname(dictionary * d, int n); 00077 00078 00079 /*-------------------------------------------------------------------------*/ 00080 /** 00081 @brief Save a dictionary to a loadable ini file 00082 @param d Dictionary to dump 00083 @param f Opened file pointer to dump to 00084 @return void 00085 00086 This function dumps a given dictionary into a loadable ini file. 00087 It is Ok to specify @c stderr or @c stdout as output files. 00088 */ 00089 /*--------------------------------------------------------------------------*/ 00090 00091 void iniparser_dump_ini(dictionary * d, FILE * f); 00092 00093 /*-------------------------------------------------------------------------*/ 00094 /** 00095 @brief Dump a dictionary to an opened file pointer. 00096 @param d Dictionary to dump. 00097 @param f Opened file pointer to dump to. 00098 @return void 00099 00100 This function prints out the contents of a dictionary, one element by 00101 line, onto the provided file pointer. It is OK to specify @c stderr 00102 or @c stdout as output files. This function is meant for debugging 00103 purposes mostly. 00104 */ 00105 /*--------------------------------------------------------------------------*/ 00106 void iniparser_dump(dictionary * d, FILE * f); 00107 00108 /*-------------------------------------------------------------------------*/ 00109 /** 00110 @brief Get the string associated to a key, return NULL if not found 00111 @param d Dictionary to search 00112 @param key Key string to look for 00113 @return pointer to statically allocated character string, or NULL. 00114 00115 This function queries a dictionary for a key. A key as read from an 00116 ini file is given as "section:key". If the key cannot be found, 00117 NULL is returned. 00118 The returned char pointer is pointing to a string allocated in 00119 the dictionary, do not free or modify it. 00120 00121 This function is only provided for backwards compatibility with 00122 previous versions of iniparser. It is recommended to use 00123 iniparser_getstring() instead. 00124 */ 00125 /*--------------------------------------------------------------------------*/ 00126 char * iniparser_getstr(dictionary * d, const char * key); 00127 00128 00129 /*-------------------------------------------------------------------------*/ 00130 /** 00131 @brief Get the string associated to a key 00132 @param d Dictionary to search 00133 @param key Key string to look for 00134 @param def Default value to return if key not found. 00135 @return pointer to statically allocated character string 00136 00137 This function queries a dictionary for a key. A key as read from an 00138 ini file is given as "section:key". If the key cannot be found, 00139 the pointer passed as 'def' is returned. 00140 The returned char pointer is pointing to a string allocated in 00141 the dictionary, do not free or modify it. 00142 */ 00143 /*--------------------------------------------------------------------------*/ 00144 char * iniparser_getstring(dictionary * d, const char * key, char * def); 00145 00146 /*-------------------------------------------------------------------------*/ 00147 /** 00148 @brief Get the string associated to a key, convert to an int 00149 @param d Dictionary to search 00150 @param key Key string to look for 00151 @param notfound Value to return in case of error 00152 @return integer 00153 00154 This function queries a dictionary for a key. A key as read from an 00155 ini file is given as "section:key". If the key cannot be found, 00156 the notfound value is returned. 00157 */ 00158 /*--------------------------------------------------------------------------*/ 00159 int iniparser_getint(dictionary * d, const char * key, int notfound); 00160 00161 /*-------------------------------------------------------------------------*/ 00162 /** 00163 @brief Get the string associated to a key, convert to a double 00164 @param d Dictionary to search 00165 @param key Key string to look for 00166 @param notfound Value to return in case of error 00167 @return double 00168 00169 This function queries a dictionary for a key. A key as read from an 00170 ini file is given as "section:key". If the key cannot be found, 00171 the notfound value is returned. 00172 */ 00173 /*--------------------------------------------------------------------------*/ 00174 double iniparser_getdouble(dictionary * d, char * key, double notfound); 00175 00176 /*-------------------------------------------------------------------------*/ 00177 /** 00178 @brief Get the string associated to a key, convert to a boolean 00179 @param d Dictionary to search 00180 @param key Key string to look for 00181 @param notfound Value to return in case of error 00182 @return integer 00183 00184 This function queries a dictionary for a key. A key as read from an 00185 ini file is given as "section:key". If the key cannot be found, 00186 the notfound value is returned. 00187 00188 A true boolean is found if one of the following is matched: 00189 00190 - A string starting with 'y' 00191 - A string starting with 'Y' 00192 - A string starting with 't' 00193 - A string starting with 'T' 00194 - A string starting with '1' 00195 00196 A false boolean is found if one of the following is matched: 00197 00198 - A string starting with 'n' 00199 - A string starting with 'N' 00200 - A string starting with 'f' 00201 - A string starting with 'F' 00202 - A string starting with '0' 00203 00204 The notfound value returned if no boolean is identified, does not 00205 necessarily have to be 0 or 1. 00206 */ 00207 /*--------------------------------------------------------------------------*/ 00208 int iniparser_getboolean(dictionary * d, const char * key, int notfound); 00209 00210 00211 /*-------------------------------------------------------------------------*/ 00212 /** 00213 @brief Set an entry in a dictionary. 00214 @param ini Dictionary to modify. 00215 @param entry Entry to modify (entry name) 00216 @param val New value to associate to the entry. 00217 @return int 0 if Ok, -1 otherwise. 00218 00219 If the given entry can be found in the dictionary, it is modified to 00220 contain the provided value. If it cannot be found, -1 is returned. 00221 It is Ok to set val to NULL. 00222 */ 00223 /*--------------------------------------------------------------------------*/ 00224 00225 int iniparser_setstr(dictionary * ini, char * entry, char * val); 00226 00227 /*-------------------------------------------------------------------------*/ 00228 /** 00229 @brief Delete an entry in a dictionary 00230 @param ini Dictionary to modify 00231 @param entry Entry to delete (entry name) 00232 @return void 00233 00234 If the given entry can be found, it is deleted from the dictionary. 00235 */ 00236 /*--------------------------------------------------------------------------*/ 00237 void iniparser_unset(dictionary * ini, char * entry); 00238 00239 /*-------------------------------------------------------------------------*/ 00240 /** 00241 @brief Finds out if a given entry exists in a dictionary 00242 @param ini Dictionary to search 00243 @param entry Name of the entry to look for 00244 @return integer 1 if entry exists, 0 otherwise 00245 00246 Finds out if a given entry exists in the dictionary. Since sections 00247 are stored as keys with NULL associated values, this is the only way 00248 of querying for the presence of sections in a dictionary. 00249 */ 00250 /*--------------------------------------------------------------------------*/ 00251 int iniparser_find_entry(dictionary * ini, char * entry) ; 00252 00253 /*-------------------------------------------------------------------------*/ 00254 /** 00255 @brief Parse an ini file and return an allocated dictionary object 00256 @param ininame Name of the ini file to read. 00257 @return Pointer to newly allocated dictionary 00258 00259 This is the parser for ini files. This function is called, providing 00260 the name of the file to be read. It returns a dictionary object that 00261 should not be accessed directly, but through accessor functions 00262 instead. 00263 00264 The returned dictionary must be freed using iniparser_freedict(). 00265 */ 00266 /*--------------------------------------------------------------------------*/ 00267 dictionary * iniparser_load(const char * ininame); 00268 00269 /*-------------------------------------------------------------------------*/ 00270 /** 00271 @brief Free all memory associated to an ini dictionary 00272 @param d Dictionary to free 00273 @return void 00274 00275 Free all memory associated to an ini dictionary. 00276 It is mandatory to call this function before the dictionary object 00277 gets out of the current context. 00278 */ 00279 /*--------------------------------------------------------------------------*/ 00280 void iniparser_freedict(dictionary * d); 00281 00282 #endif