David Smart / IniManager

A simple .ini file interface.

Dependents:   Smart-WiFly-WebServer SignalGenerator WattEye X10Svr

IniManager.h@18:282ed56d983b, 2016-12-28 (annotated)

Committer:
WiredHome
Date:
Wed Dec 28 00:21:01 2016 +0000
Revision:
18:282ed56d983b
Parent:
15:3fc2b87a234d
Parent:
16:82e0f8747b95
Child:
19:8f394a5f3758
Revised the ReadString and WriteString to return a failure code, rather than a boolean. This made the APIs incompatible, but this can be selected at construction or when setting the file, in order to be backward compatible.

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