David Smart / IniManager

A simple .ini file interface.

Dependents:   Smart-WiFly-WebServer SignalGenerator WattEye X10Svr

IniManager.h@15:3fc2b87a234d, 2016-12-11 (annotated)

Committer:
WiredHome
Date:
Sun Dec 11 14:05:17 2016 +0000
Revision:
15:3fc2b87a234d
Parent:
14:af370f01dfef
Child:
18:282ed56d983b
Add methods for iterating over sections and keys

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 0:ae5bf432c249 7 /** A simple ini file manager.
WiredHome 0:ae5bf432c249 8 *
WiredHome 0:ae5bf432c249 9 * This is a simple ini file manager intended for low duty cycle usage.
WiredHome 0:ae5bf432c249 10 *
WiredHome 0:ae5bf432c249 11 * It follows an old "Windows" style of ini file format with section, key, and value.
WiredHome 0:ae5bf432c249 12 * This version only operates on strings at this time.
WiredHome 0:ae5bf432c249 13 *
WiredHome 0:ae5bf432c249 14 * As a "simple" ini file manager, this version does not cache anything internally.
WiredHome 0:ae5bf432c249 15 * This comes at the "cost" that each write transaction will read and replace the
WiredHome 0:ae5bf432c249 16 * ini file. Read transactions will open and scan the file.
WiredHome 0:ae5bf432c249 17 *
WiredHome 0:ae5bf432c249 18 * Also, an internal stack-frame buffer is used to manage the read operations. As
WiredHome 0:ae5bf432c249 19 * such, no single record in the file can exceed this buffer size (compile time set
WiredHome 0:ae5bf432c249 20 * with a default of 250 bytes). A single record for a section is surrounded with
WiredHome 0:ae5bf432c249 21 * '[' and ']' and a new line appended. A single record for an entry within a
WiredHome 0:ae5bf432c249 22 * section for a key, value pair is separated with an '=' and a new line appended.
WiredHome 0:ae5bf432c249 23 * @code
WiredHome 0:ae5bf432c249 24 * [section name]
WiredHome 0:ae5bf432c249 25 * Key name=value for Key name
WiredHome 0:ae5bf432c249 26 * Another key=another value
WiredHome 0:ae5bf432c249 27 * @endcode
WiredHome 0:ae5bf432c249 28 */
WiredHome 0:ae5bf432c249 29 class INI
WiredHome 0:ae5bf432c249 30 {
WiredHome 0:ae5bf432c249 31 public:
WiredHome 6:cd28ab597256 32 /** Constructor for an INI file interface.
WiredHome 0:ae5bf432c249 33 *
WiredHome 6:cd28ab597256 34 * Constructor for an INI file interface.
WiredHome 6:cd28ab597256 35 *
WiredHome 6:cd28ab597256 36 * @param[in] file is the filename to manage. Memory is allocated to hold
WiredHome 0:ae5bf432c249 37 * a private copy of the filename. Be sure that this parameter
WiredHome 0:ae5bf432c249 38 * has the right path prefix based on what file system you have.
WiredHome 0:ae5bf432c249 39 */
WiredHome 5:bfeb0882bd82 40 INI(const char * file = NULL);
WiredHome 0:ae5bf432c249 41
WiredHome 0:ae5bf432c249 42 /** destructor for the ini manager.
WiredHome 0:ae5bf432c249 43 *
WiredHome 0:ae5bf432c249 44 * releases the memory allocation.
WiredHome 0:ae5bf432c249 45 */
WiredHome 0:ae5bf432c249 46 ~INI(void);
WiredHome 0:ae5bf432c249 47
WiredHome 8:f128b10dfab1 48 /** Determine if a file exists
WiredHome 8:f128b10dfab1 49 *
WiredHome 8:f128b10dfab1 50 * This API can be used to determine if a file exists. The file may
WiredHome 8:f128b10dfab1 51 * be specified as a parameter, but if no parameter is supplied it will
WiredHome 8:f128b10dfab1 52 * then check to see if the INI file exists. This is either the file
WiredHome 8:f128b10dfab1 53 * passed to the constructor, or the file passed to the SetFile API.
WiredHome 8:f128b10dfab1 54 *
WiredHome 8:f128b10dfab1 55 * @param[in] file is the optional filename to check for existance.
WiredHome 8:f128b10dfab1 56 * @returns true if the file exists.
WiredHome 8:f128b10dfab1 57 */
WiredHome 8:f128b10dfab1 58 bool Exists(const char * file = NULL);
WiredHome 8:f128b10dfab1 59
WiredHome 5:bfeb0882bd82 60 /** set the file to use
WiredHome 5:bfeb0882bd82 61 *
WiredHome 5:bfeb0882bd82 62 * If not set at the time of construction, or if a change is needed, this
WiredHome 5:bfeb0882bd82 63 * API can be used.
WiredHome 5:bfeb0882bd82 64 *
WiredHome 6:cd28ab597256 65 * @param[in] file is the filename to manage.
WiredHome 5:bfeb0882bd82 66 * @returns true if success, false if memory could not be allocated.
WiredHome 5:bfeb0882bd82 67 */
WiredHome 5:bfeb0882bd82 68 bool SetFile(const char * file);
WiredHome 5:bfeb0882bd82 69
WiredHome 14:af370f01dfef 70 /** get the filename in use
WiredHome 14:af370f01dfef 71 *
WiredHome 14:af370f01dfef 72 * @returns pointer to the filename
WiredHome 14:af370f01dfef 73 */
WiredHome 14:af370f01dfef 74 const char * GetFile(void) { return iniFile; }
WiredHome 14:af370f01dfef 75
WiredHome 0:ae5bf432c249 76 /** Read a string from the ini file - if it exists.
WiredHome 0:ae5bf432c249 77 *
WiredHome 0:ae5bf432c249 78 * This searches the ini file for the named section and key and if found it will
WiredHome 0:ae5bf432c249 79 * return the string associated with that entry into a user supplied buffer.
WiredHome 0:ae5bf432c249 80 *
WiredHome 6:cd28ab597256 81 * @param[in] section is the name of the section to search.
WiredHome 6:cd28ab597256 82 * @param[in] key is the name of the key to search.
WiredHome 6:cd28ab597256 83 * @param[out] buffer is the caller provided buffer for this method to put the string into.
WiredHome 6:cd28ab597256 84 * @param[in] bufferSize is the caller provided declaration of the available space.
WiredHome 6:cd28ab597256 85 * @param[in] defaultString is an optional parameter that sets the buffer if the section/key is not found.
WiredHome 0:ae5bf432c249 86 *
WiredHome 0:ae5bf432c249 87 * @return true if the section, key, and value are found AND the value will fit in the buffer
WiredHome 0:ae5bf432c249 88 * in which case it is written into the buffer; false otherwise.
WiredHome 0:ae5bf432c249 89 */
WiredHome 0:ae5bf432c249 90 bool ReadString(const char * section, const char * key, char * buffer, size_t bufferSize, const char * defaultString = NULL);
WiredHome 0:ae5bf432c249 91
WiredHome 12:6cf929bde139 92 /** Read a long integer from the ini file - if it exists.
WiredHome 12:6cf929bde139 93 *
WiredHome 12:6cf929bde139 94 * This searches the ini file for the named section and key and if found it will
WiredHome 12:6cf929bde139 95 * return the long integer value from that entry.
WiredHome 12:6cf929bde139 96 *
WiredHome 12:6cf929bde139 97 * @param[in] section is the name of the section to search.
WiredHome 12:6cf929bde139 98 * @param[in] key is the name of the key to search.
WiredHome 12:6cf929bde139 99 * @param[in] defaultValue is the default value to return if the entry is not found.
WiredHome 12:6cf929bde139 100 *
WiredHome 12:6cf929bde139 101 * @return the value read, or the defaultVaule.
WiredHome 12:6cf929bde139 102 */
WiredHome 12:6cf929bde139 103 long int ReadLongInt(const char * section, const char * key, long int defaultValue);
WiredHome 12:6cf929bde139 104
WiredHome 0:ae5bf432c249 105 /** Writes a string into the ini file
WiredHome 0:ae5bf432c249 106 *
WiredHome 0:ae5bf432c249 107 * This writes a given string into an ini file in the named section and key.
WiredHome 0:ae5bf432c249 108 *
WiredHome 6:cd28ab597256 109 * @param[in] section is the name of the section to search.
WiredHome 6:cd28ab597256 110 * @param[in] key is the name of the key to search.
WiredHome 6:cd28ab597256 111 * @param[in] buffer is the caller provided buffer containing the string to write. If
WiredHome 0:ae5bf432c249 112 * buffer is NULL, then any existing entry is removed.
WiredHome 0:ae5bf432c249 113 *
WiredHome 0:ae5bf432c249 114 * @return true if the write was successful; false otherwise.
WiredHome 0:ae5bf432c249 115 */
WiredHome 10:57b93035ad82 116 bool WriteString(const char * section, const char * key, const char * buffer);
WiredHome 0:ae5bf432c249 117
WiredHome 15:3fc2b87a234d 118
WiredHome 15:3fc2b87a234d 119 /** Get Section, or Next Section name
WiredHome 15:3fc2b87a234d 120 *
WiredHome 15:3fc2b87a234d 121 * This can be used to walk the list of section names in a file.
WiredHome 15:3fc2b87a234d 122 *
WiredHome 15:3fc2b87a234d 123 * @param[in] After is the name of the section to search after. When NULL, it
WiredHome 15:3fc2b87a234d 124 * is a "find-first" method.
WiredHome 15:3fc2b87a234d 125 * @param[out] buffer is the caller provided buffer for this method to put the string into.
WiredHome 15:3fc2b87a234d 126 * @param[in] bufferSize is the caller provided declaration of the available space.
WiredHome 15:3fc2b87a234d 127 * @returns true if a new section was found, false otherwise.
WiredHome 15:3fc2b87a234d 128 */
WiredHome 15:3fc2b87a234d 129 bool GetNextSection(const char * after, char * buffer, size_t bufferSize);
WiredHome 15:3fc2b87a234d 130
WiredHome 15:3fc2b87a234d 131
WiredHome 15:3fc2b87a234d 132 /** Get the first Key, or the next Key, within a section
WiredHome 15:3fc2b87a234d 133 *
WiredHome 15:3fc2b87a234d 134 * This can be used to walk the list of keys in a file.
WiredHome 15:3fc2b87a234d 135 *
WiredHome 15:3fc2b87a234d 136 * @param[in] Section is the name of the section to search.
WiredHome 15:3fc2b87a234d 137 * @param[in] After is the name of the key to search after. When NULL, it
WiredHome 15:3fc2b87a234d 138 * is a "find-first" method.
WiredHome 15:3fc2b87a234d 139 * @param[out] buffer is the caller provided buffer for this method to put the string into.
WiredHome 15:3fc2b87a234d 140 * @param[in] bufferSize is the caller provided declaration of the available space.
WiredHome 15:3fc2b87a234d 141 * @returns true if a new key was found, false otherwise.
WiredHome 15:3fc2b87a234d 142 */
WiredHome 15:3fc2b87a234d 143 bool GetNextKey(const char * Section, const char * after, char * buffer, size_t bufferSize);
WiredHome 15:3fc2b87a234d 144
WiredHome 15:3fc2b87a234d 145
WiredHome 0:ae5bf432c249 146 private:
WiredHome 0:ae5bf432c249 147 char * iniFile;
WiredHome 0:ae5bf432c249 148
WiredHome 8:f128b10dfab1 149 /** Cleanup temporary files.
WiredHome 0:ae5bf432c249 150 *
WiredHome 8:f128b10dfab1 151 * This will attempt to clean up any temporary files. This can happen
WiredHome 8:f128b10dfab1 152 * while writing a new file, if something went wrong and the program
WiredHome 8:f128b10dfab1 153 * crashed or otherwise could not complete the process.
WiredHome 8:f128b10dfab1 154 * This will look for the temp files, try to finish processing them
WiredHome 8:f128b10dfab1 155 * and remove the extraneous.
WiredHome 0:ae5bf432c249 156 *
WiredHome 0:ae5bf432c249 157 * @return true, always until I find a reason not to.
WiredHome 0:ae5bf432c249 158 */
WiredHome 8:f128b10dfab1 159 bool CleanUp();
WiredHome 0:ae5bf432c249 160
WiredHome 0:ae5bf432c249 161 /** Rename a file
WiredHome 0:ae5bf432c249 162 *
WiredHome 0:ae5bf432c249 163 * This version also works on the local file system.
WiredHome 0:ae5bf432c249 164 *
WiredHome 6:cd28ab597256 165 * @param[in] oldfname is the old file name
WiredHome 6:cd28ab597256 166 * @param[in] newfname is the new file name
WiredHome 0:ae5bf432c249 167 * @returns 0 on success, -1 on error
WiredHome 0:ae5bf432c249 168 */
WiredHome 0:ae5bf432c249 169 int Rename(const char *oldfname, const char *newfname);
WiredHome 0:ae5bf432c249 170
WiredHome 0:ae5bf432c249 171 /** Copy a file
WiredHome 0:ae5bf432c249 172 *
WiredHome 0:ae5bf432c249 173 * This version also works on the local file system.
WiredHome 0:ae5bf432c249 174 *
WiredHome 6:cd28ab597256 175 * @param[in] src is the source file
WiredHome 6:cd28ab597256 176 * @param[in] dst is the destination file
WiredHome 0:ae5bf432c249 177 * @returns 0 on success, -1 on error
WiredHome 0:ae5bf432c249 178 */
WiredHome 0:ae5bf432c249 179 int Copy(const char *src, const char *dst);
WiredHome 0:ae5bf432c249 180 };
WiredHome 0:ae5bf432c249 181
WiredHome 0:ae5bf432c249 182 #endif // INIMANAGER_H