A simple .ini file interface.
Dependents: Smart-WiFly-WebServer SignalGenerator WattEye X10Svr
IniManager.h@14:af370f01dfef, 2016-11-13 (annotated)
- Committer:
- WiredHome
- Date:
- Sun Nov 13 02:04:16 2016 +0000
- Revision:
- 14:af370f01dfef
- Parent:
- 12:6cf929bde139
- Child:
- 15:3fc2b87a234d
Add GetFile api
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 | 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 | 0:ae5bf432c249 | 118 | private: |
WiredHome | 0:ae5bf432c249 | 119 | char * iniFile; |
WiredHome | 0:ae5bf432c249 | 120 | |
WiredHome | 8:f128b10dfab1 | 121 | /** Cleanup temporary files. |
WiredHome | 0:ae5bf432c249 | 122 | * |
WiredHome | 8:f128b10dfab1 | 123 | * This will attempt to clean up any temporary files. This can happen |
WiredHome | 8:f128b10dfab1 | 124 | * while writing a new file, if something went wrong and the program |
WiredHome | 8:f128b10dfab1 | 125 | * crashed or otherwise could not complete the process. |
WiredHome | 8:f128b10dfab1 | 126 | * This will look for the temp files, try to finish processing them |
WiredHome | 8:f128b10dfab1 | 127 | * and remove the extraneous. |
WiredHome | 0:ae5bf432c249 | 128 | * |
WiredHome | 0:ae5bf432c249 | 129 | * @return true, always until I find a reason not to. |
WiredHome | 0:ae5bf432c249 | 130 | */ |
WiredHome | 8:f128b10dfab1 | 131 | bool CleanUp(); |
WiredHome | 0:ae5bf432c249 | 132 | |
WiredHome | 0:ae5bf432c249 | 133 | /** Rename a file |
WiredHome | 0:ae5bf432c249 | 134 | * |
WiredHome | 0:ae5bf432c249 | 135 | * This version also works on the local file system. |
WiredHome | 0:ae5bf432c249 | 136 | * |
WiredHome | 6:cd28ab597256 | 137 | * @param[in] oldfname is the old file name |
WiredHome | 6:cd28ab597256 | 138 | * @param[in] newfname is the new file name |
WiredHome | 0:ae5bf432c249 | 139 | * @returns 0 on success, -1 on error |
WiredHome | 0:ae5bf432c249 | 140 | */ |
WiredHome | 0:ae5bf432c249 | 141 | int Rename(const char *oldfname, const char *newfname); |
WiredHome | 0:ae5bf432c249 | 142 | |
WiredHome | 0:ae5bf432c249 | 143 | /** Copy a file |
WiredHome | 0:ae5bf432c249 | 144 | * |
WiredHome | 0:ae5bf432c249 | 145 | * This version also works on the local file system. |
WiredHome | 0:ae5bf432c249 | 146 | * |
WiredHome | 6:cd28ab597256 | 147 | * @param[in] src is the source file |
WiredHome | 6:cd28ab597256 | 148 | * @param[in] dst is the destination file |
WiredHome | 0:ae5bf432c249 | 149 | * @returns 0 on success, -1 on error |
WiredHome | 0:ae5bf432c249 | 150 | */ |
WiredHome | 0:ae5bf432c249 | 151 | int Copy(const char *src, const char *dst); |
WiredHome | 0:ae5bf432c249 | 152 | }; |
WiredHome | 0:ae5bf432c249 | 153 | |
WiredHome | 0:ae5bf432c249 | 154 | #endif // INIMANAGER_H |