David Smart / IniManager

A simple .ini file interface.

Dependents:   Smart-WiFly-WebServer SignalGenerator WattEye X10Svr

IniManager.h@28:4e7fc08a0fea, 2020-06-11 (annotated)

Committer:
WiredHome
Date:
Thu Jun 11 02:09:41 2020 +0000
Revision:
28:4e7fc08a0fea
Parent:
24:ba5fa9548f59 
Code cleanup

Who changed what in which revision?

UserRevisionLine numberNew contents of line
WiredHome 0:ae5bf432c249 1
WiredHome 0:ae5bf432c249 2 #ifndef INIMANAGER_H
WiredHome 0:ae5bf432c249 3 #define INIMANAGER_H
WiredHome 0:ae5bf432c249 4
WiredHome 0:ae5bf432c249 5 #define INTERNAL_BUF_SIZE 250
WiredHome 0:ae5bf432c249 6
WiredHome 18:282ed56d983b 7
WiredHome 18:282ed56d983b 8 /** A simple INI file manager - Version 2.
WiredHome 0:ae5bf432c249 9 *
WiredHome 0:ae5bf432c249 10 * This is a simple ini file manager intended for low duty cycle usage.
WiredHome 0:ae5bf432c249 11 *
WiredHome 0:ae5bf432c249 12 * It follows an old "Windows" style of ini file format with section, key, and value.
WiredHome 0:ae5bf432c249 13 *
WiredHome 18:282ed56d983b 14 * @note An API change offers DIFFERENT AND INCOMPATIBLE return values from the
WiredHome 19:8f394a5f3758 15 * WriteString and the ReadString APIs, however it is backward compatible,
WiredHome 19:8f394a5f3758 16 * requiring a new parameter in the constructor or the SetFile API to
WiredHome 19:8f394a5f3758 17 * access the new return values.
WiredHome 19:8f394a5f3758 18 *
WiredHome 19:8f394a5f3758 19 * @note Version 1 by default will be deprecated in a future release, probably
WiredHome 19:8f394a5f3758 20 * around mid to late 2017.
WiredHome 18:282ed56d983b 21 *
WiredHome 0:ae5bf432c249 22 * As a "simple" ini file manager, this version does not cache anything internally.
WiredHome 0:ae5bf432c249 23 * This comes at the "cost" that each write transaction will read and replace the
WiredHome 0:ae5bf432c249 24 * ini file. Read transactions will open and scan the file.
WiredHome 0:ae5bf432c249 25 *
WiredHome 0:ae5bf432c249 26 * Also, an internal stack-frame buffer is used to manage the read operations. As
WiredHome 0:ae5bf432c249 27 * such, no single record in the file can exceed this buffer size (compile time set
WiredHome 23:18b5f3d7ef14 28 * with a default of 250 bytes).
WiredHome 23:18b5f3d7ef14 29 *
WiredHome 23:18b5f3d7ef14 30 * @code
WiredHome 23:18b5f3d7ef14 31 * INI ini("/local/settings.ini");
WiredHome 23:18b5f3d7ef14 32 * ...
WiredHome 23:18b5f3d7ef14 33 * char buf[10];
WiredHome 23:18b5f3d7ef14 34 * sprintf_s(buf, 10, "%d", daymask);
WiredHome 23:18b5f3d7ef14 35 * if (INI::INI_SUCCESS == ini.WriteString("Alarm", "Daymask", buf)) {
WiredHome 23:18b5f3d7ef14 36 * ...
WiredHome 23:18b5f3d7ef14 37 * }
WiredHome 23:18b5f3d7ef14 38 * ...
WiredHome 23:18b5f3d7ef14 39 * uint8_t x = (uint8_t)ReadLongInt("Alarm", "Daymask", 0);
WiredHome 23:18b5f3d7ef14 40 * ...
WiredHome 23:18b5f3d7ef14 41 * @endcode
WiredHome 23:18b5f3d7ef14 42 *
WiredHome 23:18b5f3d7ef14 43 * A single record for a section is surrounded with '[' and ']' and a new line
WiredHome 23:18b5f3d7ef14 44 * appended. A single record for an entry within a section for a key, value pair
WiredHome 23:18b5f3d7ef14 45 * is separated with an '=' and a new line appended.
WiredHome 0:ae5bf432c249 46 * @code
WiredHome 0:ae5bf432c249 47 * [section name]
WiredHome 0:ae5bf432c249 48 * Key name=value for Key name
WiredHome 0:ae5bf432c249 49 * Another key=another value
WiredHome 0:ae5bf432c249 50 * @endcode
WiredHome 0:ae5bf432c249 51 */
WiredHome 0:ae5bf432c249 52 class INI
WiredHome 0:ae5bf432c249 53 {
WiredHome 0:ae5bf432c249 54 public:
WiredHome 18:282ed56d983b 55
WiredHome 18:282ed56d983b 56 /** Return values
WiredHome 18:282ed56d983b 57 *
WiredHome 18:282ed56d983b 58 * Functions may return a status code as follows. Where the API supports
WiredHome 18:282ed56d983b 59 * a default, and on a Fail code, that value will be returned, if it
WiredHome 18:282ed56d983b 60 * fits in the available buffer.
WiredHome 18:282ed56d983b 61 *
WiredHome 18:282ed56d983b 62 * @note Version 1 returned only a success or failure value from the ReadString
WiredHome 18:282ed56d983b 63 * and the WriteString APIs. Version 2 returns incompatible and different
WiredHome 18:282ed56d983b 64 * values. The selection of version 1 vs. version 2 is made in either
WiredHome 18:282ed56d983b 65 * the constructor, or in the SetFile API.
WiredHome 18:282ed56d983b 66 */
WiredHome 18:282ed56d983b 67 typedef enum {
WiredHome 18:282ed56d983b 68 INI_V1_FAIL = 0, ///< Version 1 return value - Fail
WiredHome 18:282ed56d983b 69 INI_V1_SUCCESS = 1, ///< Version 1 return value - Success
WiredHome 18:282ed56d983b 70 INI_SUCCESS = 0, ///< Success - operation succeeded
WiredHome 18:282ed56d983b 71 INI_NO_FILE_SPEC, ///< Fail - no file was specified
WiredHome 18:282ed56d983b 72 INI_FILE_NOT_FOUND, ///< Fail - ini file not found, or failed to open
WiredHome 18:282ed56d983b 73 INI_SECTION_NOT_FOUND, ///< Fail - section not found
WiredHome 18:282ed56d983b 74 INI_KEY_NOT_FOUND, ///< Fail - key not found
WiredHome 18:282ed56d983b 75 INI_BUF_TOO_SMALL, ///< Fail - buffer to small for value
WiredHome 18:282ed56d983b 76 INI_INTERNAL_ERROR ///< Fail - internal error - can't alloc buffers
WiredHome 18:282ed56d983b 77 } INI_Return;
WiredHome 18:282ed56d983b 78
WiredHome 6:cd28ab597256 79 /** Constructor for an INI file interface.
WiredHome 0:ae5bf432c249 80 *
WiredHome 6:cd28ab597256 81 * Constructor for an INI file interface.
WiredHome 6:cd28ab597256 82 *
WiredHome 6:cd28ab597256 83 * @param[in] file is the filename to manage. Memory is allocated to hold
WiredHome 0:ae5bf432c249 84 * a private copy of the filename. Be sure that this parameter
WiredHome 0:ae5bf432c249 85 * has the right path prefix based on what file system you have.
WiredHome 18:282ed56d983b 86 * @param[in] Version is an optional parameter that defines whether
WiredHome 18:282ed56d983b 87 * the return value of the ReadString and WriteString APIs
WiredHome 22:1ad96fcc5731 88 * are version 1 or version 2 compatible. The default is version 2.
WiredHome 0:ae5bf432c249 89 */
WiredHome 22:1ad96fcc5731 90 INI(const char * file = NULL, int Version = 2);
WiredHome 0:ae5bf432c249 91
WiredHome 0:ae5bf432c249 92 /** destructor for the ini manager.
WiredHome 0:ae5bf432c249 93 *
WiredHome 0:ae5bf432c249 94 * releases the memory allocation.
WiredHome 0:ae5bf432c249 95 */
WiredHome 0:ae5bf432c249 96 ~INI(void);
WiredHome 0:ae5bf432c249 97
WiredHome 8:f128b10dfab1 98 /** Determine if a file exists
WiredHome 8:f128b10dfab1 99 *
WiredHome 8:f128b10dfab1 100 * This API can be used to determine if a file exists. The file may
WiredHome 8:f128b10dfab1 101 * be specified as a parameter, but if no parameter is supplied it will
WiredHome 8:f128b10dfab1 102 * then check to see if the INI file exists. This is either the file
WiredHome 8:f128b10dfab1 103 * passed to the constructor, or the file passed to the SetFile API.
WiredHome 8:f128b10dfab1 104 *
WiredHome 8:f128b10dfab1 105 * @param[in] file is the optional filename to check for existance.
WiredHome 8:f128b10dfab1 106 * @returns true if the file exists.
WiredHome 8:f128b10dfab1 107 */
WiredHome 8:f128b10dfab1 108 bool Exists(const char * file = NULL);
WiredHome 8:f128b10dfab1 109
WiredHome 5:bfeb0882bd82 110 /** set the file to use
WiredHome 5:bfeb0882bd82 111 *
WiredHome 5:bfeb0882bd82 112 * If not set at the time of construction, or if a change is needed, this
WiredHome 5:bfeb0882bd82 113 * API can be used.
WiredHome 5:bfeb0882bd82 114 *
WiredHome 6:cd28ab597256 115 * @param[in] file is the filename to manage.
WiredHome 18:282ed56d983b 116 * @param[in] Version is an optional parameter that defines whether
WiredHome 18:282ed56d983b 117 * the return value of the ReadString and WriteString APIs
WiredHome 22:1ad96fcc5731 118 * are version 1 or version 2 compatible. The default is version 2.
WiredHome 5:bfeb0882bd82 119 * @returns true if success, false if memory could not be allocated.
WiredHome 5:bfeb0882bd82 120 */
WiredHome 22:1ad96fcc5731 121 bool SetFile(const char * file, int Version = 2);
WiredHome 5:bfeb0882bd82 122
WiredHome 14:af370f01dfef 123 /** get the filename in use
WiredHome 14:af370f01dfef 124 *
WiredHome 14:af370f01dfef 125 * @returns pointer to the filename
WiredHome 14:af370f01dfef 126 */
WiredHome 14:af370f01dfef 127 const char * GetFile(void) { return iniFile; }
WiredHome 5:bfeb0882bd82 128
WiredHome 0:ae5bf432c249 129 /** Read a string from the ini file - if it exists.
WiredHome 0:ae5bf432c249 130 *
WiredHome 0:ae5bf432c249 131 * This searches the ini file for the named section and key and if found it will
WiredHome 0:ae5bf432c249 132 * return the string associated with that entry into a user supplied buffer.
WiredHome 0:ae5bf432c249 133 *
WiredHome 6:cd28ab597256 134 * @param[in] section is the name of the section to search.
WiredHome 6:cd28ab597256 135 * @param[in] key is the name of the key to search.
WiredHome 6:cd28ab597256 136 * @param[out] buffer is the caller provided buffer for this method to put the string into.
WiredHome 6:cd28ab597256 137 * @param[in] bufferSize is the caller provided declaration of the available space.
WiredHome 6:cd28ab597256 138 * @param[in] defaultString is an optional parameter that sets the buffer if the section/key is not found.
WiredHome 18:282ed56d983b 139 * if defaultString is NULL (or omitted), and if the item cannot be found,
WiredHome 18:282ed56d983b 140 * it will return INI_KEY_NOT_FOUND.
WiredHome 0:ae5bf432c249 141 *
WiredHome 18:282ed56d983b 142 * @return INI_SUCCESS if the file, section, key, and value are found, and it fits into the specified buffer.
WiredHome 18:282ed56d983b 143 * @return INI_NO_FILE_SPEC if the ini file was never set.
WiredHome 18:282ed56d983b 144 * @return INI_FILE_NOT_FOUND if the ini file was specified, but cannot be found as specified.
WiredHome 18:282ed56d983b 145 * @return INI_SECTION_NOT_FOUND if the section was not found.
WiredHome 18:282ed56d983b 146 * @return INI_KEY_NOT_FOUND if the key was not found.
WiredHome 18:282ed56d983b 147 * @return INI_BUF_TOO_SMALL if everything was found, but it could not fit into the specified buffer.
WiredHome 0:ae5bf432c249 148 */
WiredHome 18:282ed56d983b 149 INI_Return ReadString(const char * section, const char * key, char * buffer, size_t bufferSize, const char * defaultString = NULL);
WiredHome 0:ae5bf432c249 150
WiredHome 12:6cf929bde139 151 /** Read a long integer from the ini file - if it exists.
WiredHome 12:6cf929bde139 152 *
WiredHome 12:6cf929bde139 153 * This searches the ini file for the named section and key and if found it will
WiredHome 12:6cf929bde139 154 * return the long integer value from that entry.
WiredHome 12:6cf929bde139 155 *
WiredHome 12:6cf929bde139 156 * @param[in] section is the name of the section to search.
WiredHome 12:6cf929bde139 157 * @param[in] key is the name of the key to search.
WiredHome 12:6cf929bde139 158 * @param[in] defaultValue is the default value to return if the entry is not found.
WiredHome 12:6cf929bde139 159 *
WiredHome 18:282ed56d983b 160 * @return the value read, or the defaultVaule; no failure code is returned.
WiredHome 12:6cf929bde139 161 */
WiredHome 12:6cf929bde139 162 long int ReadLongInt(const char * section, const char * key, long int defaultValue);
WiredHome 12:6cf929bde139 163
WiredHome 0:ae5bf432c249 164 /** Writes a string into the ini file
WiredHome 0:ae5bf432c249 165 *
WiredHome 0:ae5bf432c249 166 * This writes a given string into an ini file in the named section and key.
WiredHome 0:ae5bf432c249 167 *
WiredHome 6:cd28ab597256 168 * @param[in] section is the name of the section to search.
WiredHome 6:cd28ab597256 169 * @param[in] key is the name of the key to search.
WiredHome 6:cd28ab597256 170 * @param[in] buffer is the caller provided buffer containing the string to write. If
WiredHome 0:ae5bf432c249 171 * buffer is NULL, then any existing entry is removed.
WiredHome 16:82e0f8747b95 172 * @param[in] len is the number of characters to write, if specified. If not specified,
WiredHome 16:82e0f8747b95 173 * the length of the buffer defines the length to write.
WiredHome 0:ae5bf432c249 174 *
WiredHome 24:ba5fa9548f59 175 * @return INI_SUCCESS if the file, section, key, and value are written.
WiredHome 18:282ed56d983b 176 * @return INI_NO_FILE_SPEC if the ini file was never set.
WiredHome 18:282ed56d983b 177 * @return INI_FILE_NOT_FOUND if the ini file was specified, but cannot be found as specified.
WiredHome 18:282ed56d983b 178 * @return INI_SECTION_NOT_FOUND if the section was not found.
WiredHome 18:282ed56d983b 179 * @return INI_KEY_NOT_FOUND if the key was not found.
WiredHome 18:282ed56d983b 180 * @return INI_BUF_TOO_SMALL if everything was found, but it could not fit into the specified buffer.
WiredHome 0:ae5bf432c249 181 */
WiredHome 18:282ed56d983b 182 INI_Return WriteString(const char * section, const char * key, const char * buffer, int len = -1);
WiredHome 0:ae5bf432c249 183
WiredHome 15:3fc2b87a234d 184
WiredHome 24:ba5fa9548f59 185 /** Writes a long integer into the ini file
WiredHome 24:ba5fa9548f59 186 *
WiredHome 24:ba5fa9548f59 187 * This writes a given long integer into an ini file in the named section and key.
WiredHome 24:ba5fa9548f59 188 *
WiredHome 24:ba5fa9548f59 189 * @param[in] section is the name of the section to search.
WiredHome 24:ba5fa9548f59 190 * @param[in] key is the name of the key to search.
WiredHome 24:ba5fa9548f59 191 * @param[in] value is the long integer.
WiredHome 24:ba5fa9548f59 192 *
WiredHome 24:ba5fa9548f59 193 * @return INI_SUCCESS if the file, section, key, and value are written.
WiredHome 24:ba5fa9548f59 194 * @return INI_NO_FILE_SPEC if the ini file was never set.
WiredHome 24:ba5fa9548f59 195 * @return INI_FILE_NOT_FOUND if the ini file was specified, but cannot be found as specified.
WiredHome 24:ba5fa9548f59 196 * @return INI_SECTION_NOT_FOUND if the section was not found.
WiredHome 24:ba5fa9548f59 197 * @return INI_KEY_NOT_FOUND if the key was not found.
WiredHome 24:ba5fa9548f59 198 * @return INI_BUF_TOO_SMALL if everything was found, but it could not fit into the specified buffer.
WiredHome 24:ba5fa9548f59 199 */
WiredHome 24:ba5fa9548f59 200 INI_Return WriteLongInt(const char * section, const char * key, long int value);
WiredHome 24:ba5fa9548f59 201
WiredHome 15:3fc2b87a234d 202 /** Get Section, or Next Section name
WiredHome 15:3fc2b87a234d 203 *
WiredHome 15:3fc2b87a234d 204 * This can be used to walk the list of section names in a file.
WiredHome 15:3fc2b87a234d 205 *
WiredHome 15:3fc2b87a234d 206 * @param[in] After is the name of the section to search after. When NULL, it
WiredHome 15:3fc2b87a234d 207 * is a "find-first" method.
WiredHome 15:3fc2b87a234d 208 * @param[out] buffer is the caller provided buffer for this method to put the string into.
WiredHome 15:3fc2b87a234d 209 * @param[in] bufferSize is the caller provided declaration of the available space.
WiredHome 15:3fc2b87a234d 210 * @returns true if a new section was found, false otherwise.
WiredHome 0:ae5bf432c249 211 */
WiredHome 15:3fc2b87a234d 212 bool GetNextSection(const char * after, char * buffer, size_t bufferSize);
WiredHome 15:3fc2b87a234d 213
WiredHome 15:3fc2b87a234d 214
WiredHome 15:3fc2b87a234d 215 /** Get the first Key, or the next Key, within a section
WiredHome 15:3fc2b87a234d 216 *
WiredHome 15:3fc2b87a234d 217 * This can be used to walk the list of keys in a file.
WiredHome 15:3fc2b87a234d 218 *
WiredHome 15:3fc2b87a234d 219 * @param[in] Section is the name of the section to search.
WiredHome 15:3fc2b87a234d 220 * @param[in] After is the name of the key to search after. When NULL, it
WiredHome 15:3fc2b87a234d 221 * is a "find-first" method.
WiredHome 15:3fc2b87a234d 222 * @param[out] buffer is the caller provided buffer for this method to put the string into.
WiredHome 15:3fc2b87a234d 223 * @param[in] bufferSize is the caller provided declaration of the available space.
WiredHome 15:3fc2b87a234d 224 * @returns true if a new key was found, false otherwise.
WiredHome 15:3fc2b87a234d 225 */
WiredHome 15:3fc2b87a234d 226 bool GetNextKey(const char * Section, const char * after, char * buffer, size_t bufferSize);
WiredHome 15:3fc2b87a234d 227
WiredHome 15:3fc2b87a234d 228
WiredHome 18:282ed56d983b 229 /** Get the text message for an error return value from ReadString and WriteString.
WiredHome 18:282ed56d983b 230 *
WiredHome 18:282ed56d983b 231 * @param[in] retVal is the return value from either the ReadString or the WriteString
WiredHome 18:282ed56d983b 232 * APIs.
WiredHome 18:282ed56d983b 233 * @returns a pointer to a string which describes the return value.
WiredHome 18:282ed56d983b 234 */
WiredHome 18:282ed56d983b 235 const char * GetReturnMessage(INI_Return retVal);
WiredHome 0:ae5bf432c249 236
WiredHome 0:ae5bf432c249 237 private:
WiredHome 0:ae5bf432c249 238 char * iniFile;
WiredHome 0:ae5bf432c249 239
WiredHome 18:282ed56d983b 240 /** Version of the return values
WiredHome 18:282ed56d983b 241 */
WiredHome 18:282ed56d983b 242 int version;
WiredHome 18:282ed56d983b 243
WiredHome 8:f128b10dfab1 244 /** Cleanup temporary files.
WiredHome 0:ae5bf432c249 245 *
WiredHome 8:f128b10dfab1 246 * This will attempt to clean up any temporary files. This can happen
WiredHome 8:f128b10dfab1 247 * while writing a new file, if something went wrong and the program
WiredHome 8:f128b10dfab1 248 * crashed or otherwise could not complete the process.
WiredHome 8:f128b10dfab1 249 * This will look for the temp files, try to finish processing them
WiredHome 8:f128b10dfab1 250 * and remove the extraneous.
WiredHome 0:ae5bf432c249 251 *
WiredHome 0:ae5bf432c249 252 * @return true, always until I find a reason not to.
WiredHome 0:ae5bf432c249 253 */
WiredHome 8:f128b10dfab1 254 bool CleanUp();
WiredHome 0:ae5bf432c249 255
WiredHome 0:ae5bf432c249 256 /** Rename a file
WiredHome 0:ae5bf432c249 257 *
WiredHome 0:ae5bf432c249 258 * This version also works on the local file system.
WiredHome 0:ae5bf432c249 259 *
WiredHome 6:cd28ab597256 260 * @param[in] oldfname is the old file name
WiredHome 6:cd28ab597256 261 * @param[in] newfname is the new file name
WiredHome 0:ae5bf432c249 262 * @returns 0 on success, -1 on error
WiredHome 0:ae5bf432c249 263 */
WiredHome 0:ae5bf432c249 264 int Rename(const char *oldfname, const char *newfname);
WiredHome 0:ae5bf432c249 265
WiredHome 0:ae5bf432c249 266 /** Copy a file
WiredHome 0:ae5bf432c249 267 *
WiredHome 0:ae5bf432c249 268 * This version also works on the local file system.
WiredHome 0:ae5bf432c249 269 *
WiredHome 6:cd28ab597256 270 * @param[in] src is the source file
WiredHome 6:cd28ab597256 271 * @param[in] dst is the destination file
WiredHome 0:ae5bf432c249 272 * @returns 0 on success, -1 on error
WiredHome 0:ae5bf432c249 273 */
WiredHome 0:ae5bf432c249 274 int Copy(const char *src, const char *dst);
WiredHome 0:ae5bf432c249 275 };
WiredHome 0:ae5bf432c249 276
WiredHome 0:ae5bf432c249 277 #endif // INIMANAGER_H