File content as of revision 5:bfeb0882bd82:

#ifndef INIMANAGER_H
#define INIMANAGER_H

#define INTERNAL_BUF_SIZE 250

/** A simple ini file manager.
*
* 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.
*
* 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.
*
* Also, an internal stack-frame buffer is used to manage the read operations. As
* such, no single record in the file can exceed this buffer size (compile time set
* with a default of 250 bytes). A single record for a section is surrounded with
* '[' and ']' and a new line appended. A single record for an entry within a
* section for a key, value pair is separated with an '=' and a new line appended.
* @code
* [section name]
* Key name=value for Key name
* Another key=another value
* @endcode
*/
class INI
{
public:
    /** constructor accepts a filename
    *
    * @param 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.
    */
    INI(const char * file = NULL);

    /** destructor for the ini manager.
    *
    * releases the memory allocation.
    */
    ~INI(void);

    /** set the file to use
    *
    * If not set at the time of construction, or if a change is needed, this
    * API can be used.
    *
    * @param file is the filename to manage.
    * @returns true if success, false if memory could not be allocated.
    */
    bool SetFile(const char * file);

    /** Read a string from the ini file - if it exists.
    *
    * This searches the ini file for the named section and key and if found it will
    * return the string associated with that entry into a user supplied buffer.
    * 
    * @param section is the name of the section to search.
    * @param key is the name of the key to search.
    * @param buffer is the caller provided buffer for this method to put the string into.
    * @param bufferSize is the caller provided declaration of the available space.
    * @param defaultString is an optional parameter that sets the buffer if the section/key is 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.
    */
    bool ReadString(const char * section, const char * key, char * buffer, size_t bufferSize, const char * defaultString = NULL);

    /** Writes a string into the ini file
    *
    * This writes a given string into an ini file in the named section and key.
    * 
    * @param section is the name of the section to search.
    * @param key is the name of the key to search.
    * @param buffer is the caller provided buffer containing the string to write. If
    *       buffer is NULL, then any existing entry is removed.
    *
    * @return true if the write was successful; false otherwise.
    */
    bool WriteString(const char * section, const char * key, char * buffer);

private:
    char * iniFile;

    /** Crash recover if we can.
    *
    * This will attempt to crash recover. If while writing a new file, it could not
    * complete the process, it may be able to complete the process on the next access.
    *
    * @return true, always until I find a reason not to.
    */
    bool CrashRecover();
    
    /** Rename a file
    *
    * This version also works on the local file system.
    *
    * @param oldfname is the old file name
    * @param newfname is the new file name
    * @returns 0 on success, -1 on error
    */
    int Rename(const char *oldfname, const char *newfname);
    
    /** Copy a file
    *
    * This version also works on the local file system.
    *
    * @param src is the source file
    * @param dst is the destination file
    * @returns 0 on success, -1 on error
    */
    int Copy(const char *src, const char *dst);
};

#endif // INIMANAGER_H