David Smart / IniManager

A simple .ini file interface.

Dependents:   Smart-WiFly-WebServer SignalGenerator WattEye X10Svr

IniManager.h@0:ae5bf432c249, 2013-08-12 (annotated)

Committer:
WiredHome
Date:
Mon Aug 12 22:57:54 2013 +0000
Revision:
0:ae5bf432c249
Child:
5:bfeb0882bd82
A simple ini file interface.

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 0:ae5bf432c249 32 /** constructor accepts a filename
WiredHome 0:ae5bf432c249 33 *
WiredHome 0:ae5bf432c249 34 * @param file is the filename to manage. Memory is allocated to hold
WiredHome 0:ae5bf432c249 35 * a private copy of the filename. Be sure that this parameter
WiredHome 0:ae5bf432c249 36 * has the right path prefix based on what file system you have.
WiredHome 0:ae5bf432c249 37 */
WiredHome 0:ae5bf432c249 38 INI(const char * file);
WiredHome 0:ae5bf432c249 39
WiredHome 0:ae5bf432c249 40 /** destructor for the ini manager.
WiredHome 0:ae5bf432c249 41 *
WiredHome 0:ae5bf432c249 42 * releases the memory allocation.
WiredHome 0:ae5bf432c249 43 */
WiredHome 0:ae5bf432c249 44 ~INI(void);
WiredHome 0:ae5bf432c249 45
WiredHome 0:ae5bf432c249 46 /** Read a string from the ini file - if it exists.
WiredHome 0:ae5bf432c249 47 *
WiredHome 0:ae5bf432c249 48 * This searches the ini file for the named section and key and if found it will
WiredHome 0:ae5bf432c249 49 * return the string associated with that entry into a user supplied buffer.
WiredHome 0:ae5bf432c249 50 *
WiredHome 0:ae5bf432c249 51 * @param section is the name of the section to search.
WiredHome 0:ae5bf432c249 52 * @param key is the name of the key to search.
WiredHome 0:ae5bf432c249 53 * @param buffer is the caller provided buffer for this method to put the string into.
WiredHome 0:ae5bf432c249 54 * @param bufferSize is the caller provided declaration of the available space.
WiredHome 0:ae5bf432c249 55 * @param defaultString is an optional parameter that sets the buffer if the section/key is not found.
WiredHome 0:ae5bf432c249 56 *
WiredHome 0:ae5bf432c249 57 * @return true if the section, key, and value are found AND the value will fit in the buffer
WiredHome 0:ae5bf432c249 58 * in which case it is written into the buffer; false otherwise.
WiredHome 0:ae5bf432c249 59 */
WiredHome 0:ae5bf432c249 60 bool ReadString(const char * section, const char * key, char * buffer, size_t bufferSize, const char * defaultString = NULL);
WiredHome 0:ae5bf432c249 61
WiredHome 0:ae5bf432c249 62 /** Writes a string into the ini file
WiredHome 0:ae5bf432c249 63 *
WiredHome 0:ae5bf432c249 64 * This writes a given string into an ini file in the named section and key.
WiredHome 0:ae5bf432c249 65 *
WiredHome 0:ae5bf432c249 66 * @param section is the name of the section to search.
WiredHome 0:ae5bf432c249 67 * @param key is the name of the key to search.
WiredHome 0:ae5bf432c249 68 * @param buffer is the caller provided buffer containing the string to write. If
WiredHome 0:ae5bf432c249 69 * buffer is NULL, then any existing entry is removed.
WiredHome 0:ae5bf432c249 70 *
WiredHome 0:ae5bf432c249 71 * @return true if the write was successful; false otherwise.
WiredHome 0:ae5bf432c249 72 */
WiredHome 0:ae5bf432c249 73 bool WriteString(const char * section, const char * key, char * buffer);
WiredHome 0:ae5bf432c249 74
WiredHome 0:ae5bf432c249 75 private:
WiredHome 0:ae5bf432c249 76 char * iniFile;
WiredHome 0:ae5bf432c249 77
WiredHome 0:ae5bf432c249 78 /** Crash recover if we can.
WiredHome 0:ae5bf432c249 79 *
WiredHome 0:ae5bf432c249 80 * This will attempt to crash recover. If while writing a new file, it could not
WiredHome 0:ae5bf432c249 81 * complete the process, it may be able to complete the process on the next access.
WiredHome 0:ae5bf432c249 82 *
WiredHome 0:ae5bf432c249 83 * @return true, always until I find a reason not to.
WiredHome 0:ae5bf432c249 84 */
WiredHome 0:ae5bf432c249 85 bool CrashRecover();
WiredHome 0:ae5bf432c249 86
WiredHome 0:ae5bf432c249 87 /** Rename a file
WiredHome 0:ae5bf432c249 88 *
WiredHome 0:ae5bf432c249 89 * This version also works on the local file system.
WiredHome 0:ae5bf432c249 90 *
WiredHome 0:ae5bf432c249 91 * @param oldfname is the old file name
WiredHome 0:ae5bf432c249 92 * @param newfname is the new file name
WiredHome 0:ae5bf432c249 93 * @returns 0 on success, -1 on error
WiredHome 0:ae5bf432c249 94 */
WiredHome 0:ae5bf432c249 95 int Rename(const char *oldfname, const char *newfname);
WiredHome 0:ae5bf432c249 96
WiredHome 0:ae5bf432c249 97 /** Copy a file
WiredHome 0:ae5bf432c249 98 *
WiredHome 0:ae5bf432c249 99 * This version also works on the local file system.
WiredHome 0:ae5bf432c249 100 *
WiredHome 0:ae5bf432c249 101 * @param src is the source file
WiredHome 0:ae5bf432c249 102 * @param dst is the destination file
WiredHome 0:ae5bf432c249 103 * @returns 0 on success, -1 on error
WiredHome 0:ae5bf432c249 104 */
WiredHome 0:ae5bf432c249 105 int Copy(const char *src, const char *dst);
WiredHome 0:ae5bf432c249 106 };
WiredHome 0:ae5bf432c249 107
WiredHome 0:ae5bf432c249 108 #endif // INIMANAGER_H