IniManager.h

00001 
00002 #ifndef INIMANAGER_H
00003 #define INIMANAGER_H
00004 
00005 #define INTERNAL_BUF_SIZE 250
00006 
00007 
00008 /** A simple INI file manager - Version 2.
00009 *
00010 * This is a simple ini file manager intended for low duty cycle usage. 
00011 *
00012 * It follows an old "Windows" style of ini file format with section, key, and value.
00013 *
00014 * @note An API change offers DIFFERENT AND INCOMPATIBLE return values from the 
00015 *       WriteString and the ReadString APIs, however it is backward compatible,
00016 *       requiring a new parameter in the constructor or the SetFile API to 
00017 *       access the new return values.
00018 *
00019 * @note Version 1 by default will be deprecated in a future release, probably 
00020 *       around mid to late 2017.
00021 * 
00022 * As a "simple" ini file manager, this version does not cache anything internally.
00023 * This comes at the "cost" that each write transaction will read and replace the
00024 * ini file. Read transactions will open and scan the file.
00025 *
00026 * Also, an internal stack-frame buffer is used to manage the read operations. As
00027 * such, no single record in the file can exceed this buffer size (compile time set
00028 * with a default of 250 bytes). 
00029 *
00030 * @code
00031 * INI ini("/local/settings.ini");
00032 * ...
00033 * char buf[10];
00034 * sprintf_s(buf, 10, "%d", daymask);
00035 * if (INI::INI_SUCCESS == ini.WriteString("Alarm", "Daymask", buf)) {
00036 *     ...
00037 * }
00038 * ...
00039 * uint8_t x = (uint8_t)ReadLongInt("Alarm", "Daymask", 0);
00040 * ...
00041 * @endcode 
00042 *
00043 * A single record for a section is surrounded with '[' and ']' and a new line 
00044 * appended. A single record for an entry within a section for a key, value pair 
00045 * is separated with an '=' and a new line appended.
00046 * @code
00047 * [section name]
00048 * Key name=value for Key name
00049 * Another key=another value
00050 * @endcode
00051 */
00052 class INI
00053 {
00054 public:
00055 
00056     /** Return values 
00057     *
00058     * Functions may return a status code as follows. Where the API supports
00059     * a default, and on a Fail code, that value will be returned, if it
00060     * fits in the available buffer.
00061     *
00062     * @note Version 1 returned only a success or failure value from the ReadString
00063     *       and the WriteString APIs. Version 2 returns incompatible and different
00064     *       values. The selection of version 1 vs. version 2 is made in either
00065     *       the constructor, or in the SetFile API.
00066     */
00067     typedef enum {
00068         INI_V1_FAIL = 0,        ///< Version 1 return value - Fail
00069         INI_V1_SUCCESS = 1,     ///< Version 1 return value - Success
00070         INI_SUCCESS = 0,        ///< Success - operation succeeded
00071         INI_NO_FILE_SPEC,       ///< Fail - no file was specified
00072         INI_FILE_NOT_FOUND,     ///< Fail - ini file not found, or failed to open
00073         INI_SECTION_NOT_FOUND,  ///< Fail - section not found
00074         INI_KEY_NOT_FOUND,      ///< Fail - key not found
00075         INI_BUF_TOO_SMALL,      ///< Fail - buffer to small for value
00076         INI_INTERNAL_ERROR      ///< Fail - internal error - can't alloc buffers
00077     } INI_Return;
00078 
00079     /** Constructor for an INI file interface.
00080     *
00081     * Constructor for an INI file interface.
00082     *
00083     * @param[in] file is the filename to manage. Memory is allocated to hold
00084     *       a private copy of the filename. Be sure that this parameter
00085     *       has the right path prefix based on what file system you have.
00086     * @param[in] Version is an optional parameter that defines whether 
00087     *       the return value of the ReadString and WriteString APIs 
00088     *       are version 1 or version 2 compatible. The default is version 2.
00089     */
00090     INI(const char * file = NULL, int Version = 2);
00091 
00092     /** destructor for the ini manager.
00093     *
00094     * releases the memory allocation.
00095     */
00096     ~INI(void);
00097 
00098     /** Determine if a file exists
00099     *
00100     * This API can be used to determine if a file exists. The file may
00101     * be specified as a parameter, but if no parameter is supplied it will
00102     * then check to see if the INI file exists. This is either the file
00103     * passed to the constructor, or the file passed to the SetFile API.
00104     *
00105     * @param[in] file is the optional filename to check for existance.
00106     * @returns true if the file exists.
00107     */
00108     bool Exists(const char * file = NULL);
00109 
00110     /** set the file to use
00111     *
00112     * If not set at the time of construction, or if a change is needed, this
00113     * API can be used.
00114     *
00115     * @param[in] file is the filename to manage.
00116     * @param[in] Version is an optional parameter that defines whether 
00117     *       the return value of the ReadString and WriteString APIs 
00118     *       are version 1 or version 2 compatible. The default is version 2.
00119     * @returns true if success, false if memory could not be allocated.
00120     */
00121     bool SetFile(const char * file, int Version = 2);
00122 
00123     /** get the filename in use
00124     *
00125     * @returns pointer to the filename
00126     */
00127     const char * GetFile(void) { return iniFile; }
00128 
00129     /** Read a string from the ini file - if it exists.
00130     *
00131     * This searches the ini file for the named section and key and if found it will
00132     * return the string associated with that entry into a user supplied buffer.
00133     * 
00134     * @param[in] section is the name of the section to search.
00135     * @param[in] key is the name of the key to search.
00136     * @param[out] buffer is the caller provided buffer for this method to put the string into.
00137     * @param[in] bufferSize is the caller provided declaration of the available space.
00138     * @param[in] defaultString is an optional parameter that sets the buffer if the section/key is not found.
00139     *           if defaultString is NULL (or omitted), and if the item cannot be found, 
00140     *           it will return INI_KEY_NOT_FOUND.
00141     * 
00142     * @return INI_SUCCESS if the file, section, key, and value are found, and it fits into the specified buffer.
00143     * @return INI_NO_FILE_SPEC if the ini file was never set.
00144     * @return INI_FILE_NOT_FOUND if the ini file was specified, but cannot be found as specified.
00145     * @return INI_SECTION_NOT_FOUND if the section was not found.
00146     * @return INI_KEY_NOT_FOUND if the key was not found.
00147     * @return INI_BUF_TOO_SMALL if everything was found, but it could not fit into the specified buffer.
00148     */
00149     INI_Return ReadString(const char * section, const char * key, char * buffer, size_t bufferSize, const char * defaultString = NULL);
00150 
00151     /** Read a long integer from the ini file - if it exists.
00152     *
00153     * This searches the ini file for the named section and key and if found it will 
00154     * return the long integer value from that entry.
00155     *
00156     * @param[in] section is the name of the section to search.
00157     * @param[in] key is the name of the key to search.
00158     * @param[in] defaultValue is the default value to return if the entry is not found.
00159     *
00160     * @return the value read, or the defaultVaule; no failure code is returned.
00161     */
00162     long int ReadLongInt(const char * section, const char * key, long int defaultValue);
00163 
00164     /** Writes a string into the ini file
00165     *
00166     * This writes a given string into an ini file in the named section and key.
00167     * 
00168     * @param[in] section is the name of the section to search.
00169     * @param[in] key is the name of the key to search.
00170     * @param[in] buffer is the caller provided buffer containing the string to write. If
00171     *       buffer is NULL, then any existing entry is removed.
00172     * @param[in] len is the number of characters to write, if specified. If not specified,
00173     *       the length of the buffer defines the length to write.
00174     *
00175     * @return INI_SUCCESS if the file, section, key, and value are written.
00176     * @return INI_NO_FILE_SPEC if the ini file was never set.
00177     * @return INI_FILE_NOT_FOUND if the ini file was specified, but cannot be found as specified.
00178     * @return INI_SECTION_NOT_FOUND if the section was not found.
00179     * @return INI_KEY_NOT_FOUND if the key was not found.
00180     * @return INI_BUF_TOO_SMALL if everything was found, but it could not fit into the specified buffer.
00181     */
00182     INI_Return WriteString(const char * section, const char * key, const char * buffer, int len = -1);
00183 
00184 
00185     /** Writes a long integer into the ini file
00186     *
00187     * This writes a given long integer into an ini file in the named section and key.
00188     * 
00189     * @param[in] section is the name of the section to search.
00190     * @param[in] key is the name of the key to search.
00191     * @param[in] value is the long integer.
00192     *
00193     * @return INI_SUCCESS if the file, section, key, and value are written.
00194     * @return INI_NO_FILE_SPEC if the ini file was never set.
00195     * @return INI_FILE_NOT_FOUND if the ini file was specified, but cannot be found as specified.
00196     * @return INI_SECTION_NOT_FOUND if the section was not found.
00197     * @return INI_KEY_NOT_FOUND if the key was not found.
00198     * @return INI_BUF_TOO_SMALL if everything was found, but it could not fit into the specified buffer.
00199     */
00200     INI_Return WriteLongInt(const char * section, const char * key, long int value);
00201 
00202     /** Get Section, or Next Section name
00203     *
00204     * This can be used to walk the list of section names in a file.
00205     *
00206     * @param[in] After is the name of the section to search after. When NULL, it
00207     *           is a "find-first" method.
00208     * @param[out] buffer is the caller provided buffer for this method to put the string into.
00209     * @param[in] bufferSize is the caller provided declaration of the available space.
00210     * @returns true if a new section was found, false otherwise.
00211     */
00212     bool GetNextSection(const char * after, char * buffer, size_t bufferSize);
00213     
00214 
00215     /** Get the first Key, or the next Key, within a section
00216     *
00217     * This can be used to walk the list of keys in a file.
00218     *
00219     * @param[in] Section is the name of the section to search.
00220     * @param[in] After is the name of the key to search after. When NULL, it
00221     *           is a "find-first" method.
00222     * @param[out] buffer is the caller provided buffer for this method to put the string into.
00223     * @param[in] bufferSize is the caller provided declaration of the available space.
00224     * @returns true if a new key was found, false otherwise.
00225     */
00226     bool GetNextKey(const char * Section, const char * after, char * buffer, size_t bufferSize);
00227     
00228 
00229     /** Get the text message for an error return value from ReadString and WriteString.
00230     *
00231     * @param[in] retVal is the return value from either the ReadString or the WriteString
00232     *           APIs.
00233     * @returns a pointer to a string which describes the return value.
00234     */
00235     const char * GetReturnMessage(INI_Return retVal);
00236 
00237 private:
00238     char * iniFile;
00239 
00240     /** Version of the return values
00241     */
00242     int version;
00243     
00244     /** Cleanup temporary files.
00245     *
00246     * This will attempt to clean up any temporary files. This can happen
00247     * while writing a new file, if something went wrong and the program 
00248     * crashed or otherwise could not complete the process.
00249     * This will look for the temp files, try to finish processing them
00250     * and remove the extraneous.
00251     *
00252     * @return true, always until I find a reason not to.
00253     */
00254     bool CleanUp();
00255     
00256     /** Rename a file
00257     *
00258     * This version also works on the local file system.
00259     *
00260     * @param[in] oldfname is the old file name
00261     * @param[in] newfname is the new file name
00262     * @returns 0 on success, -1 on error
00263     */
00264     int Rename(const char *oldfname, const char *newfname);
00265     
00266     /** Copy a file
00267     *
00268     * This version also works on the local file system.
00269     *
00270     * @param[in] src is the source file
00271     * @param[in] dst is the destination file
00272     * @returns 0 on success, -1 on error
00273     */
00274     int Copy(const char *src, const char *dst);
00275 };
00276 
00277 #endif // INIMANAGER_H