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