Diff: IniManager.h

Revision:

18:282ed56d983b

Parent:

15:3fc2b87a234d

Parent:

16:82e0f8747b95

Child:

19:8f394a5f3758

--- a/IniManager.h	Sun Dec 11 14:05:17 2016 +0000
+++ b/IniManager.h	Wed Dec 28 00:21:01 2016 +0000
@@ -4,13 +4,16 @@
 
 #define INTERNAL_BUF_SIZE 250
 
-/** A simple ini file manager.
+
+/** A simple INI file manager - Version 2.
 *
 * This is a simple ini file manager intended for low duty cycle usage. 
 *
 * It follows an old "Windows" style of ini file format with section, key, and value.
-* This version only operates on strings at this time.
 *
+* @note An API change offers DIFFERENT AND INCOMPATIBLE return values from the 
+*       WriteString and the ReadString APIs. 
+* 
 * As a "simple" ini file manager, this version does not cache anything internally.
 * This comes at the "cost" that each write transaction will read and replace the
 * ini file. Read transactions will open and scan the file.
@@ -29,6 +32,30 @@
 class INI
 {
 public:
+
+    /** Return values 
+    *
+    * Functions may return a status code as follows. Where the API supports
+    * a default, and on a Fail code, that value will be returned, if it
+    * fits in the available buffer.
+    *
+    * @note Version 1 returned only a success or failure value from the ReadString
+    *       and the WriteString APIs. Version 2 returns incompatible and different
+    *       values. The selection of version 1 vs. version 2 is made in either
+    *       the constructor, or in the SetFile API.
+    */
+    typedef enum {
+        INI_V1_FAIL = 0,        ///< Version 1 return value - Fail
+        INI_V1_SUCCESS = 1,     ///< Version 1 return value - Success
+        INI_SUCCESS = 0,        ///< Success - operation succeeded
+        INI_NO_FILE_SPEC,       ///< Fail - no file was specified
+        INI_FILE_NOT_FOUND,     ///< Fail - ini file not found, or failed to open
+        INI_SECTION_NOT_FOUND,  ///< Fail - section not found
+        INI_KEY_NOT_FOUND,      ///< Fail - key not found
+        INI_BUF_TOO_SMALL,      ///< Fail - buffer to small for value
+        INI_INTERNAL_ERROR      ///< Fail - internal error - can't alloc buffers
+    } INI_Return;
+
     /** Constructor for an INI file interface.
     *
     * Constructor for an INI file interface.
@@ -36,8 +63,11 @@
     * @param[in] file is the filename to manage. Memory is allocated to hold
     *       a private copy of the filename. Be sure that this parameter
     *       has the right path prefix based on what file system you have.
+    * @param[in] Version is an optional parameter that defines whether 
+    *       the return value of the ReadString and WriteString APIs 
+    *       are version 1 or version 2 compatible. The default is version 1.
     */
-    INI(const char * file = NULL);
+    INI(const char * file = NULL, int Version = 1);
 
     /** destructor for the ini manager.
     *
@@ -63,9 +93,12 @@
     * API can be used.
     *
     * @param[in] file is the filename to manage.
+    * @param[in] Version is an optional parameter that defines whether 
+    *       the return value of the ReadString and WriteString APIs 
+    *       are version 1 or version 2 compatible. The default is version 1.
     * @returns true if success, false if memory could not be allocated.
     */
-    bool SetFile(const char * file);
+    bool SetFile(const char * file, int Version = 1);
 
     /** get the filename in use
     *
@@ -83,11 +116,17 @@
     * @param[out] buffer is the caller provided buffer for this method to put the string into.
     * @param[in] bufferSize is the caller provided declaration of the available space.
     * @param[in] defaultString is an optional parameter that sets the buffer if the section/key is not found.
+    *           if defaultString is NULL (or omitted), and if the item cannot be found, 
+    *           it will return INI_KEY_NOT_FOUND.
     * 
-    * @return true if the section, key, and value are found AND the value will fit in the buffer
-    *       in which case it is written into the buffer; false otherwise.
+    * @return INI_SUCCESS if the file, section, key, and value are found, and it fits into the specified buffer.
+    * @return INI_NO_FILE_SPEC if the ini file was never set.
+    * @return INI_FILE_NOT_FOUND if the ini file was specified, but cannot be found as specified.
+    * @return INI_SECTION_NOT_FOUND if the section was not found.
+    * @return INI_KEY_NOT_FOUND if the key was not found.
+    * @return INI_BUF_TOO_SMALL if everything was found, but it could not fit into the specified buffer.
     */
-    bool ReadString(const char * section, const char * key, char * buffer, size_t bufferSize, const char * defaultString = NULL);
+    INI_Return ReadString(const char * section, const char * key, char * buffer, size_t bufferSize, const char * defaultString = NULL);
 
     /** Read a long integer from the ini file - if it exists.
     *
@@ -98,7 +137,7 @@
     * @param[in] key is the name of the key to search.
     * @param[in] defaultValue is the default value to return if the entry is not found.
     *
-    * @return the value read, or the defaultVaule.
+    * @return the value read, or the defaultVaule; no failure code is returned.
     */
     long int ReadLongInt(const char * section, const char * key, long int defaultValue);
 
@@ -110,10 +149,17 @@
     * @param[in] key is the name of the key to search.
     * @param[in] buffer is the caller provided buffer containing the string to write. If
     *       buffer is NULL, then any existing entry is removed.
+    * @param[in] len is the number of characters to write, if specified. If not specified,
+    *       the length of the buffer defines the length to write.
     *
-    * @return true if the write was successful; false otherwise.
+    * @return INI_SUCCESS if the file, section, key, and value are found, and it fits into the specified buffer.
+    * @return INI_NO_FILE_SPEC if the ini file was never set.
+    * @return INI_FILE_NOT_FOUND if the ini file was specified, but cannot be found as specified.
+    * @return INI_SECTION_NOT_FOUND if the section was not found.
+    * @return INI_KEY_NOT_FOUND if the key was not found.
+    * @return INI_BUF_TOO_SMALL if everything was found, but it could not fit into the specified buffer.
     */
-    bool WriteString(const char * section, const char * key, const char * buffer);
+    INI_Return WriteString(const char * section, const char * key, const char * buffer, int len = -1);
 
 
     /** Get Section, or Next Section name
@@ -143,9 +189,21 @@
     bool GetNextKey(const char * Section, const char * after, char * buffer, size_t bufferSize);
     
 
+    /** Get the text message for an error return value from ReadString and WriteString.
+    *
+    * @param[in] retVal is the return value from either the ReadString or the WriteString
+    *           APIs.
+    * @returns a pointer to a string which describes the return value.
+    */
+    const char * GetReturnMessage(INI_Return retVal);
+
 private:
     char * iniFile;
 
+    /** Version of the return values
+    */
+    int version;
+    
     /** Cleanup temporary files.
     *
     * This will attempt to clean up any temporary files. This can happen