inidefns.h

Go to the documentation of this file.

/****
 * \file inidefns.h <mi32/inidefns.h>
 * \brief Include file for Ini...() functions
 *
 * \if NODOC
 * $Id: inidefns.h_v 1.67 2004/03/30 16:23:39 mju Exp $
 *
 * $Log: inidefns.h_v $
 * Revision 1.67  2004/03/30 16:23:39  mju
 * Add IniList fns.
 *
 * Revision 1.66  2004/03/30 14:54:06  mju
 * Eliminate obsolete iniflags.
 * Make iniopen variant using filepath non-inline.
 *
 * Revision 1.65  2003/11/20 21:17:07  msmith
 * added set to ini auto
 *
 * Revision 1.64  2003/10/09 14:17:28  msmith
 * Updating documentation.
 *
 * Revision 1.63  2003/09/17 17:44:38  mju
 * Add IniWrite variant for MGUI::ID if 64-bit platform.
 *
 * Revision 1.62  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.61  2003/09/08 20:39:13  dwilliss
 * Added doxygen tags for start/end function groups
 *
 * Revision 1.60  2003/05/14 14:19:35  mju
 * Add INIHND::IsOpen and chg Open to check if path matches current.
 *
 * Revision 1.59  2003/05/14 13:59:43  mju
 * Add IniGetFilePath.
 *
 * Revision 1.58  2003/05/13 17:09:44  msmith
 * INI_AUTO back to internal data.
 *
 * Revision 1.57  2003/05/07 21:42:19  msmith
 * INI_AUTO now references external data.
 *
 * Revision 1.56  2003/05/07 14:46:25  mju
 * Need both const and non-const casts for INI_AUTO templates.
 *
 * Revision 1.55  2003/05/06 21:07:15  msmith
 * Added INI_AUTO, INI_NOTIFIER, INI_AUTO_ENUM, and
 * INI_NOTIFIER_ENUM classes.
 *
 * Revision 1.54  2003/04/15 13:33:42  mju
 * Move fns using RECT2D to rect header to avoid circular dependency.
 *
 * Revision 1.52  2003/04/09 21:19:27  mju
 * Add iniflag_WriteRequired.
 *
 * Revision 1.51  2003/04/08 21:46:18  dwilliss
 * Changed template _T to _CT because MacOS X's ctype defines an _T
 *
 * Revision 1.50  2003/02/21 20:52:29  mju
 * Delete some obsolete/unsupported flags.
 * Update documentation.
 *
 * Revision 1.49  2003/02/17 21:39:14  mju
 * Remove iniflags_nothomepath as unused and not supported.
 *
 * Revision 1.48  2003/02/17 18:50:56  mju
 * Add readonly parm to inihnd.openhost with default of true.
 *
 * Revision 1.47  2003/02/17 18:48:47  mju
 * Remove openserver method from INIHND.
 *
 * Revision 1.46  2003/02/17 18:36:36  mju
 * Remove inifile_server defn as not used anymore.
 *
 * Revision 1.45  2002/09/09 13:50:33  mju
 * Deprecate inigetfilename as not used anyway.
 *
 * Revision 1.44  2002/09/09 13:40:28  mju
 * "Remove" deprecated stuff except if building DLL.
 *
 * Revision 1.43  2002/06/07 15:09:44  dwilliss
 * clarify a comment
 *
 * Revision 1.42  2002/03/28 16:28:10  mju
 * Deprecate non-type-safe INI functions.
 * Retire old ReadINI.../WriteINI functions.
 *
 * Revision 1.41  2001/09/27 18:01:55  scowan
 * Added a create no lock file flag.
 *
 * Revision 1.38  2001/02/28 18:44:37  mju
 * Add read/write overloads for 'long' and 'unsigned long' for WIN32.
 *
 * Revision 1.37  2000/10/31 15:55:06  mju
 * Add IniRead/WriteStringMultiLine fns.
 *
 * Revision 1.36  2000/10/27 17:20:07  mju
 * Add INIHND class.
 *
 * Revision 1.35  2000/08/30 20:42:10  mju
 * Eliminate some IniWrite overloads by passing integer and floating-point by value.
 *
 * Revision 1.34  2000/07/19 16:52:33  mju
 * Add docs for some inlines.
 *
 * Revision 1.33  2000/06/23 15:50:38  mju
 * Add IniReadEnum templates.
 *
 * Revision 1.32  2000/06/23 15:32:50  mju
 * Add IniReadBoolean().
 *
 * Revision 1.31  2000/06/23 14:11:18  mju
 * Add function-specific comments for type-safe read/write functions.
 * Deprecate old INIRead/Write functions.
 *
 * Revision 1.30  2000/06/09 17:46:39  sparsons
 * Genitor documentation.
 *
 * Revision 1.29  2000/03/23 14:58:29  mju
 * Always define LIBEXPORT *after* all include files in case any of them undefines it.
 *
 * Revision 1.28  2000/03/22 16:26:59  mju
 * Add IniOpen() which uses FILEPATH.
 *
 * Revision 1.26  1999/11/04 14:11:24  mju
 * Include color.h knows how to copy structures.
 *
 * Revision 1.25  1999/11/03  14:59:56  mju
 * Add INITYPE_Bool.
 * Add type-safe overloads for IniRead and IniWrite.
 *
 * Revision 1.24  1999/10/26 15:22:11  scowan
 * Return const from get filename.
 *
 * Revision 1.23  1999/08/04 16:42:43  mju
 * Use "const" for data parm in IniWrite fns.
 *
 * Revision 1.1  1996/07/24  20:34:43  scowan
 * Initial revision
 * \endif
****/

#ifndef INC_MI32_INIDEFNS_H
#define INC_MI32_INIDEFNS_H

#ifndef  INC_MI32_STDDEFNS_H
   #include <mi32/stddefns.h>
#endif

#ifndef  INC_MI32_COLOR_H
   #include <mi32/color.h>
#endif

#ifndef  INC_MI32_MAPPROJ_H
   #include <mi32/mapproj.h>
#endif

#ifndef  INC_MI32_FILEPATH_H
   #include <mi32/filepath.h>
#endif


#ifdef MISYSTEMDLL
   #define LIBEXPORT MI_DLLEXPORT
#else
   #define LIBEXPORT MI_DLLIMPORT
#endif


#define INITYPE_IniStruct     0x01000000              //!< Ini structure marker
#define INITYPE_End           0                       //!< End of a list (0)
#define INITYPE_ByteBoolean   1                       //!< Read a Yes/No, 1/0, Y/N, y/n, True/False, T/F, t/f
#define INITYPE_IntBoolean    2                       //!< Read a Yes/No, 1/0, Y/N, y/n, True/False, T/F, t/f
#define INITYPE_INT8          3                       //!< Read a byte
#define INITYPE_UINT8         4                       //!< Read a unsigned byte
#define INITYPE_INT16         5                       //!< Read a word
#define INITYPE_UINT16        6                       //!< Read a unsigned word
#define INITYPE_INT32         7                       //!< Read a long
#define INITYPE_UINT32        8                       //!< Read a unsigned long
#define INITYPE_Float         9                       //!< Read a float
#define INITYPE_Double        10                      //!< Read a double
#define INITYPE_String        11                      //!< Read a string
#define INITYPE_ASCII         INITYPE_String          //!< Read a string
#define INITYPE_Unicode       12                      //!< Read a UNICODE string
#define INITYPE_UNICODE       INITYPE_Unicode
#define INITYPE_DPOINT2D      13|INITYPE_IniStruct    //!< Read a 2D point
#define INITYPE_DPOINT3D      14|INITYPE_IniStruct    //!< Read a 3D point
#define INITYPE_MAPPROJPARM   15|INITYPE_IniStruct    //!< Read a MAPPROJPARM
#define INITYPE_COLOR         17|INITYPE_IniStruct    //!< Read a COLOR
#define INITYPE_DRECT2D       18|INITYPE_IniStruct    //!< Read a DRECT2D
#define INITYPE_Bool          19                      //!< bool

//! For basefilename in IniOpen().
#define INIFILE_Standard      "tntproc.ini"
#define INIFILE_Host          "tnthost.ini"

//! Flags for Ini... functions.
#define INIFLAG_None             0
#define INIFLAG_WriteRequired    0x00000002     //!< Need write access, return error if not allowed
#define INIFLAG_ReadOnly         0x00000004     //!< Open as read-only
#define INIFLAG_InternalOnly     0x00000010     //!< Not a file, use internal buffer only


//-------------------------------------------------------------------------------------------------
//!      Function prototypes                                                                          
//-------------------------------------------------------------------------------------------------

extern "C" {

#ifndef GENERATING_DOXYGEN_OUTPUT
//! Internal functions

LIBEXPORT INT32 _iniRead (
   INIHANDLE iniptr,                   //!< Open INI file handle, NULL for default .ini file    
   const char* group,                  //!< Group to find field in, uses GetAppName() if NULL
   const char*const field,             //!< Field that the data is stored under
   UINT32 initype,                     //!< INITYPE of items to read
   void *data,                         //!< Pointer to buffer to read into, dependant on 'initype'
   INT32 count = 1                     //!< Number of items to read
   );

LIBEXPORT INT32 _iniReadString (
   INIHANDLE iniptr,                   //!< Open INI file handle, NULL for default
   const char* group,                  //!< Group to find field in, uses GetAppName() if NULL
   const char*const field,             //!< Field that data is stored in
   UINT32 initype,                     //!< INITYPE_ASCII or INITYPE_Unicode
   void *data,                         //!< Pointer to buffer to read into RETURNED
   INT32 len                           //!< Number of BYTES to read
   );

LIBEXPORT INT32 _iniReadStringAllocML (
   INIHANDLE iniptr,                   //!< Open INI file handle, NULL for default
   const char* group,                  //!< Group to find field in, uses GetAppName() if NULL
   const char*const field,             //!< Field that data is stored in
   UINT32 initype,                     //!< INITYPE_ASCII or INITYPE_Unicode
   void **data                         //!< Pointer to buffer to read into RETURNED
   );

LIBEXPORT int _iniWrite (
   INIHANDLE iniptr,                   //!< Ini file handle, NULL for default .ini file
   const char* group,                  //!< Group to find field in, uses GetAppName() if NULL
   const char* field,                  //!< Field that the data is stored under
   UINT32 initype,                     //!< Type of data to write
   const void *data,                   //!< Pointer to buffer to write from
   INT32 count                         //!< Number of entries to write
   );

LIBEXPORT int _iniWriteString (
   INIHANDLE iniptr,                   //!< Open INI file handle NULL for default
   const char *group,                  //!< Group to locate field in, uses GetAppName() if NULL
   const char *field,                  //!< Field that the data is to be stored under
   UINT32 initype,                     //!< INITYPE_ASCII or INITYPE_Unicode
   const void *data                    //!< Pointer to buffer to write from
   );

LIBEXPORT int _iniWriteStringML (
   INIHANDLE iniptr,                   //!< Open INI file handle NULL for default
   const char *group,                  //!< Group to locate field in, uses GetAppName() if NULL
   const char *field,                  //!< Field that the data is to be stored under
   UINT32 initype,                     //!< Type of data to write
   const void *data                    //!< Pointer to buffer to write from
   );

#endif // GENERATING_DOXYGEN_OUTPUT


//!:Associate with "INI File Functions"
//!\addtogroup ini INI File Functions
//!@{

//! Close handle to opened .ini file.
//!   This function should only be called when the .ini file is opened using IniOpen.
LIBEXPORT void IniClose (
   INIHANDLE iniptr                    //!< Open INI file handle, NULL for default .ini file
   );

//! Delete a field entry in the .ini file.
LIBEXPORT int IniDeleteField (
   INIHANDLE iniptr,                   //!< Open INI file handle, NULL for default .ini file
   const char* group,                  //!< Group to find field in, uses GetAppName() if NULL
   const char* field                   //!< Field to delete
   );

//! Delete a group from the .ini file.
LIBEXPORT int IniDeleteGroup (
   INIHANDLE iniptr,                   //!< Open INI file handle, NULL for default .ini file
   const char* group                   //!< Group to delete
   );

//! Get internal buffer into UNICODE string.
//! @return Number of Unicode characters in output or error < 0.
LIBEXPORT int IniGetBuffer (
   INIHANDLE iniptr,                   //!< Open INI file handle, must pass INIFLAG_InternalOnly to IniOpen()
   UNICODE **buffer                    //!< Buffer from Ini handle RETURNED, free using MmFree().
   );

//! Get path to actual Ini file.
//! Returns empty path if handle not opened or is attached to memory buffer.
LIBEXPORT const FILEPATH& IniGetFilePath (
   INIHANDLE inihandle
   );

//! Determine if ini file is writable.
//! @return 1 if it is writable, 0 if it is not.
LIBEXPORT int IniIsWritable (
   INIHANDLE iniptr                    //!< Open INI file handle, NULL for default .ini file
   );

//! Add file to preset list.
LIBEXPORT ERRVALUE IniListAdd (
   const FILEPATH& filepath
   );

//! Clear preset list.
LIBEXPORT void IniListClear (
   );


//! Open .ini file for modification.
//!
//! This function does not keep the .ini file itself open, it reads the whole file into memory and
//!   processes it internally.  If NULL is passed for 'basefilename', the INIFLAG_InternalOnly flag must
//! be specified or an error will result.  IniClose must be called to free the handle returned
//!   by this function.  This function is not needed if the 'standard' .ini file is to be accessed,
//!   the other Ini... functions will manage this internally.
//! Defined flags:      
//!      INIFLAG_ReadOnly     Do not allow writing through this handle.
//!      INIFLAG_InternalOnly Open Ini handle for use with memory buffer.  See IniGetBuffer() and IniSetBuffer() for details.
//!   Default .ini file defines:
//!      INIFILE_Host         tnthost.ini
//!         Host machine specific values, one per system.      
LIBEXPORT int IniOpen (
   const char *basefilename,           //!< Name of .ini file to open (NULL for use with INIFLAG_InternalOnly)
   INIHANDLE *iniptr,                  //!< Handle to .ini file RETURNED
   UINT32 flags = INIFLAG_None         //!< Flags
   );

//! Set application name for use when group == NULL and it overrides module name.
LIBEXPORT void IniSetAppName (
   const char *AppName
   );

//! Set internal buffer from passed UNICODE string.
LIBEXPORT int IniSetBuffer (
   INIHANDLE iniptr,                   //!< Open INI file handle, must pass INIFLAG_InternalOnly to IniOpen()
   UNICODE *buffer                     //!< Buffer to pass into Ini handle
   );

//! Write single boolean value to .ini file.
//!
//! @return Error if < 0 or number of bytes written.
//!
//! This is useful for writing constant values (TRUE or FALSE).
LIBEXPORT int IniWriteBoolean (
   INIHANDLE iniptr,                   //!< Open INI file handle NULL for default
   const char *group,                  //!< Group to locate field in, uses GetAppName() if NULL
   const char *field,                  //!< Field that the data is to be stored under
   int value                           //!< Value to write (NOT A POINTER)
   );

}  // Extern "C"

//! Open INI file specified by FILEPATH.
LIBEXPORT ERRVALUE IniOpen (
   const FILEPATH& filepath,           //!< File path to open
   INIHANDLE *iniptr,                  //!< INI handle returned
   UINT32 flags = INIFLAG_None
   );

//---------------------------------------------------------------------------------------------------------------------
#ifndef GENERATING_DOXYGEN_OUTPUT
// Removed items

#if defined(MISYSTEMDLL)

extern "C" {

//! Read a string value.
//!
//!   REMOVED.  Use type-safe IniRead versions instead.
//!
//! @return Number of 'characters' read, -1 if no entry, or error code if < -1.
//!
//! List of available types:     
//!      INITYPE_ASCII        ASCII (1-byte character) string
//!      INITYPE_Unicode      UNICODE (2-byte character) string
//! The 'size' field is used to specify the size of the buffer.  For Unicode this is NOT the same as 
//! the number of characters.  Usually this will be specified by the sizeof(...) operator.
//!   Unicode strings are stored in the .ini file as UTF8 encoding.
//!   If you want to store strings with line terminators, you are required to create your own 
//! line termination scheme.  You may use INITYPE_Unicode to read strings stored as ASCII.
LIBEXPORT INT32 IniReadString (
   INIHANDLE iniptr,                   //!< Open INI file handle, NULL for default
   const char* group,                  //!< Group to find field in, uses GetAppName() if NULL
   const char*const field,             //!< Field that data is stored in
   UINT32 initype,                     //!< INITYPE_ASCII or INITYPE_Unicode
   void *data,                         //!< Pointer to buffer to read into RETURNED
   INT32 len                           //!< Number of BYTES to read
   );

//! Read the entry from the .ini file as an allocated ASCII or UNICODE string.
//!
//!   REMOVED.  Use MISTRING::IniRead() instead.
//!
//! @return Number of 'characters' read, -1 if no entry, or error code if < -1.
//!
//! This function will not read multi-line strings, use IniReadStringAllocML for multi-line strings.
//!   Unicode strings are stored in the .ini file as UTF8 encoding.
LIBEXPORT INT32 IniReadStringAlloc (
   INIHANDLE iniptr,                   //!< Open INI file handle, NULL for default
   const char* group,                  //!< Group to find field in, uses GetAppName() if NULL
   const char*const field,             //!< Field that data is stored in
   void **data,                        //!< Pointer to buffer to read into RETURNED
   UINT32 initype                      //!< INITYPE_ASCII or INITYPE_Unicode
   );

//! Read multi-line string from .ini file.
//!
//!   REMOVED.  Use MISTRING::IniRead() instead.
//!
//! @return Number of 'characters' read, -1 if no entry, or error code if < -1.
LIBEXPORT INT32 IniReadStringAllocML (
   INIHANDLE iniptr,                   //!< Open INI file handle, NULL for default
   const char* group,                  //!< Group to find field in, uses GetAppName() if NULL
   const char*const field,             //!< Field that data is stored in
   UINT32 initype,                     //!< INITYPE_ASCII or INITYPE_Unicode
   void **data                         //!< Pointer to buffer to read into RETURNED
   );

//! Write a string to the .ini file.
//!
//!   REMOVED.  Use type-safe IniWrite versions instead.
//!
//! @return Error if < 0 or number of bytes written.
//!
//! Do NOT use this function to store multi-line strings (containing newlines).  Use IniWriteStringML.
//! Unicode strings are stored in the .ini file as UTF8 encoding.
//! List of accepted types:      
//!      INITYPE_ASCII        ASCII (1-byte character) string
//!      INITYPE_Unicode      UNICODE (2-byte character) string 
LIBEXPORT int IniWriteString (
   INIHANDLE iniptr,                   //!< Open INI file handle NULL for default
   const char *group,                  //!< Group to locate field in, uses GetAppName() if NULL
   const char *field,                  //!< Field that the data is to be stored under
   UINT32 initype,                     //!< INITYPE_ASCII or INITYPE_Unicode
   const void *data                    //!< Pointer to buffer to write from
   );

//! Write multi-line string to Ini file.
//!
//!   REMOVED.  Use type-safe IniWrite versions instead.
LIBEXPORT int IniWriteStringML (
   INIHANDLE iniptr,                   //!< Open INI file handle NULL for default
   const char *group,                  //!< Group to locate field in, uses GetAppName() if NULL
   const char *field,                  //!< Field that the data is to be stored under
   UINT32 initype,                     //!< Type of data to write
   const void *data                    //!< Pointer to buffer to write from
   );

}  // Extern "C"

#endif

#endif // GENERATING_DOXYGEN_OUTPUT

//---------------------------------------------------------------------------------------------------------------------

//! Read 'bool' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, bool& value) { return (_iniRead(hdl,group,field,INITYPE_Bool,&value,1)); }

//! Read 'bool' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, bool& value, bool dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'INT8' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, INT8& value) { return (_iniRead(hdl,group,field,INITYPE_INT8,&value,1)); }

//! Read 'INT8' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, INT8& value, INT8 dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'INT8' value from INI file with default and range check.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, INT8& value, INT8 dft, INT8 min, INT8 max) { value = dft; int err = IniRead(hdl,group,field,value); if (value < min) value = min; else if (value > max) value = max; return (err); }

//! Read 'UINT8' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UINT8& value) { return (_iniRead(hdl,group,field,INITYPE_UINT8,&value,1)); }

//! Read 'UINT8' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UINT8& value, UINT8 dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'UINT8' value from INI file with default and range.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UINT8& value, UINT8 dft, UINT8 min, UINT8 max) { value = dft; int err = IniRead(hdl,group,field,value); if (value < min) value = min; else if (value > max) value = max; return (err); }

//! Read 'INT16' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, INT16& value) { return (_iniRead(hdl,group,field,INITYPE_INT16,&value,1)); }

//! Read 'INT16' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, INT16& value, INT16 dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'INT16' value from INI file with default and range.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, INT16& value, INT16 dft, INT16 min, INT16 max) { value = dft; int err = IniRead(hdl,group,field,value); if (value < min) value = min; else if (value > max) value = max; return (err); }

//! Read 'UINT16' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UINT16& value) { return (_iniRead(hdl,group,field,INITYPE_UINT16,&value,1)); }

//! Read 'UINT16' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UINT16& value, UINT16 dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'UINT16' value from INI file with default and range.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UINT16& value, UINT16 dft, UINT16 min, UINT16 max) { value = dft; int err = IniRead(hdl,group,field,value); if (value < min) value = min; else if (value > max) value = max; return (err); }

//! Read 'INT32' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, INT32& value) { return (_iniRead(hdl,group,field,INITYPE_INT32,&value,1)); }

//! Read 'INT32' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, INT32& value, INT32 dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'INT32' value from INI file with default and range.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, INT32& value, INT32 dft, INT32 min, INT32 max) { value = dft; int err = IniRead(hdl,group,field,value); if (value < min) value = min; else if (value > max) value = max; return (err); }

//! Read 'UINT32' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UINT32& value) { return (_iniRead(hdl,group,field,INITYPE_UINT32,&value,1)); }

//! Read 'UINT32' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UINT32& value, UINT32 dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'UINT32' value from INI file with default and range.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UINT32& value, UINT32 dft, UINT32 min, UINT32 max) { value = dft; int err = IniRead(hdl,group,field,value); if (value < min) value = min; else if (value > max) value = max; return (err); }

#if defined(WIN32)

//! Read 'long' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, long& value) { return (_iniRead(hdl,group,field,INITYPE_INT32,&value,1)); }

//! Read 'long' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, long& value, long dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'long' value from INI file with default and range.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, long& value, long dft, long min, long max) { value = dft; long err = IniRead(hdl,group,field,value); if (value < min) value = min; else if (value > max) value = max; return (err); }

//! Read 'unsigned long' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, unsigned long& value) { return (_iniRead(hdl,group,field,INITYPE_INT32,&value,1)); }

//! Read 'unsigned long' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, unsigned long& value, unsigned long dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'unsigned long' value from INI file with default and range.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, unsigned long& value, unsigned long dft, unsigned long min, unsigned long max) { value = dft; long err = IniRead(hdl,group,field,value); if (value < min) value = min; else if (value > max) value = max; return (err); }

#elif !defined(INT32_is_int)

//! Read 'int' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, int& value) { return (_iniRead(hdl,group,field,INITYPE_INT32,&value,1)); }

//! Read 'int' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, int& value, int dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'int' value from INI file with default and range.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, int& value, int dft, int min, int max) { value = dft; int err = IniRead(hdl,group,field,value); if (value < min) value = min; else if (value > max) value = max; return (err); }

#endif

//! Read 'float' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, float& value) { return (_iniRead(hdl,group,field,INITYPE_Float,&value,1)); }

//! Read 'float' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, float& value, float dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'float' value from INI file with default and range.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, float& value, float dft, float min, float max) { value = dft; int err = IniRead(hdl,group,field,value); if (value < min) value = min; else if (value > max) value = max; return (err); }

//! Read 'double' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, double& value) { return (_iniRead(hdl,group,field,INITYPE_Double,&value,1)); }

//! Read 'double' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, double& value, double dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'double' value from INI file with default and range.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, double& value, double dft, double min, double max) { value = dft; int err = IniRead(hdl,group,field,value); if (value < min) value = min; else if (value > max) value = max; return (err); }

//! Read 'char* string' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, char *str, int size) { return (_iniReadString(hdl,group,field,INITYPE_ASCII,str,size)); }

//! Read 'UNICODE* string' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UNICODE *str, int size) { return (_iniReadString(hdl,group,field,INITYPE_Unicode,str,size)); }

//! Read 'COLOR' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, COLOR& value) { return (_iniRead(hdl,group,field,INITYPE_COLOR,&value,1)); }

//! Read 'COLOR' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, COLOR& value, const COLOR& dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'DPOINT2D' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, DPOINT2D& value) { return (_iniRead(hdl,group,field,INITYPE_DPOINT2D,&value,1)); }

//! Read 'DPOINT2D' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, DPOINT2D& value, const DPOINT2D& dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'DPOINT3D' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, DPOINT3D& value) { return (_iniRead(hdl,group,field,INITYPE_DPOINT3D,&value,1)); }

//! Read 'DPOINT3D' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, DPOINT3D& value, const DPOINT3D& dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read 'MAPPROJPARM' value from INI file.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, MAPPROJPARM& value) { return (_iniRead(hdl,group,field,INITYPE_MAPPROJPARM,&value,1)); }

//! Read 'MAPPROJPARM' value from INI file with default.
inline int IniRead (INIHANDLE hdl, const char *group, const char *field, MAPPROJPARM& value, const MAPPROJPARM& dft) { value = dft; return (IniRead(hdl,group,field,value)); }

//! Read general boolean value from INI file with default.
//! If the entry does not exist in the file or any error occurs the default will be returned.
inline bool IniReadBoolean (INIHANDLE hdl, const char *group, const char *field, bool dft) { bool value; IniRead(hdl,group,field,value,dft); return (value); }

//! Read 'enum' from INI file.
template <class _CT>
inline int IniReadEnum (
   INIHANDLE hdl,
   const char *group,
   const char *field,
   _CT& value
   ) {
   int err, temp;
   if ((err = IniRead(hdl,group,field,temp)) >= 0) {
      value = static_cast<_CT>(temp);
      }
   return (err);
   }

//! Read 'enum' from INI file with default.
template <class _CT>
inline int IniReadEnum (
   INIHANDLE hdl,
   const char *group,
   const char *field,
   _CT& value,
   _CT dft
   ) {
   int err, temp;
   if ((err = IniRead(hdl,group,field,temp)) >= 0) {
      value = static_cast<_CT>(temp);
      }
   else {
      value = dft;
      }
   return (err);
   }

//! Read multi-line 'char*' string from INI file.
inline int IniReadStringMultiLine (
   INIHANDLE iniptr,                   //!< Open INI file handle, NULL for default
   const char *group,                  //!< Group to find field in, uses GetAppName() if NULL
   const char *field,                  //!< Field that data is stored in
   char*& string                       //!< String to read into, allocated and returned
   ) {
   return (_iniReadStringAllocML(iniptr,group,field,INITYPE_ASCII,reinterpret_cast<void**>(&string)));
   }

//! Read multi-line 'UNICODE*' string from INI file.
inline int IniReadStringMultiLine (
   INIHANDLE iniptr,                   //!< Open INI file handle, NULL for default
   const char *group,                  //!< Group to find field in, uses GetAppName() if NULL
   const char *field,                  //!< Field that data is stored in
   UNICODE*& string                    //!< String to read into, allocated and returned
   ) {
   return (_iniReadStringAllocML(iniptr,group,field,INITYPE_Unicode,reinterpret_cast<void**>(&string)));
   }

//! Write 'bool' value to INI file.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, const bool& value) { return (IniWriteBoolean(hdl,group,field,value)); }

//! Write signed integer or enum value to INI file.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, int value) { return (_iniWrite(hdl,group,field,INITYPE_INT32,&value,1)); }

//! Write unsigned integer or enum value to INI file.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, unsigned int value) { return (_iniWrite(hdl,group,field,INITYPE_UINT32,&value,1)); }

#if defined(WIN32)

//! Write 'long' value to INI file.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, long value) { return (_iniWrite(hdl,group,field,INITYPE_INT32,&value,1)); }

//! Write 'unsigned long' value to INI file.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, unsigned long value) { return (_iniWrite(hdl,group,field,INITYPE_UINT32,&value,1)); }

#elif !defined(INT32_is_int)

//! Write 'INT32' value to INI file.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, INT32 value) { return (_iniWrite(hdl,group,field,INITYPE_INT32,&value,1)); }

//! Write 'UINT32' value to INI file.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, UINT32 value) { return (_iniWrite(hdl,group,field,INITYPE_UINT32,&value,1)); }

#endif

#if defined(LONGS_ARE_64_BIT)

//! Write 'MGUI::ID' value to INI file.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, MGUI::ID value) { INT32 temp = static_cast<INT32>(value); return (_iniWrite(hdl,group,field,INITYPE_INT32,&temp,1)); }

#endif

//! Write floating-point value to INI file.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, double value) { return (_iniWrite(hdl,group,field,INITYPE_Double,&value,1)); }

//! Write 'char* string' value to INI file.
//! Do NOT use this function to store multi-line strings (containing newlines).  Use IniWriteStringMultiLine.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, const char *str) { return (_iniWriteString(hdl,group,field,INITYPE_ASCII,str)); }

//! Write 'UNICODE* string' value to INI file.
//! Do NOT use this function to store multi-line strings (containing newlines).  Use IniWriteStringMultiLine.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, const UNICODE *str) { return (_iniWriteString(hdl,group,field,INITYPE_Unicode,str)); }

//! Write 'COLOR' value to INI file.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, const COLOR& value) { return (_iniWrite(hdl,group,field,INITYPE_COLOR,&value,1)); }

//! Write 'DPOINT2D' value to INI file.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, const DPOINT2D& value) { return (_iniWrite(hdl,group,field,INITYPE_DPOINT2D,&value,1)); }

//! Write 'DPOINT3D' value to INI file.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, const DPOINT3D& value) { return (_iniWrite(hdl,group,field,INITYPE_DPOINT3D,&value,1)); }

//! Write 'MAPPROJPARM' value to INI file.
inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, const MAPPROJPARM& value) { return (_iniWrite(hdl,group,field,INITYPE_MAPPROJPARM,&value,1)); }


//! Write multi-line 'char*' string to Ini file.
inline int IniWriteStringMultiLine (
   INIHANDLE iniptr,                   //!< Open INI file handle NULL for default
   const char *group,                  //!< Group to locate field in, uses GetAppName() if NULL
   const char *field,                  //!< Field that the data is to be stored under
   const char *string                  //!< String to write
   ) {
   return (_iniWriteStringML(iniptr,group,field,INITYPE_ASCII,string));
   }

//! Write multi-line 'UNICODE*' string to Ini file.
inline int IniWriteStringMultiLine (
   INIHANDLE iniptr,                   //!< Open INI file handle NULL for default
   const char *group,                  //!< Group to locate field in, uses GetAppName() if NULL
   const char *field,                  //!< Field that the data is to be stored under
   const UNICODE *string               //!< String to write
   ) {
   return (_iniWriteStringML(iniptr,group,field,INITYPE_Unicode,string));
   }

//!@}

//-------------------------------------------------------------------------------------------------

//! INI handle class support automatic closing of handle when going out of scope.
class INIHND {
   public:

      //! Construct unopened handle.
      INIHND (
         ): m_handle(0) { }

      //! Destructor, closes handle if open.
      ~INIHND (
         ) { Close(); }

      //! Cast to INIHANDLE - Return actual handle for use in other Ini functions.
      //! Do not use in IniClose or errors will occur.
      operator INIHANDLE (
         ) const { return (m_handle); }

      //! Close handle if open.
      void Close (
         ) { if (IsOpen()) IniClose(m_handle); m_handle = 0; }

      //! Determine if handle references 'open' file.
      bool IsOpen (
         ) const { return (m_handle != 0); }

      //! Open "tnthost.ini" file.
      ERRVALUE OpenHost (
         bool readonly = true
         ) { Close(); return (IniOpen(INIFILE_Host,&m_handle,(readonly?INIFLAG_ReadOnly:0))); }

      //! Open specified file given FILEPATH.
      ERRVALUE Open (
         const FILEPATH& filepath
         ) {
         if (IsOpen() && filepath == IniGetFilePath(m_handle)) return (0);
         Close();
         return (IniOpen(filepath,&m_handle));
         }

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      INIHANDLE m_handle;
      // UNIMPLEMENTED / UNSUPPORTED
      INIHND (const INIHND&);
      INIHND& operator= (const INIHND&);
      #endif // GENERATING_DOXYGEN_OUTPUT
   };


#undef LIBEXPORT

//! INI_AUTO is a class designed to automatically handle reading and writing of
//! data from an INI file and ensure that IniRead \ IniWrite pairs function
//! together correctly.  The constructor calls IniRead and the assignment operator calls
//! IniWrite.  The Write method allows the data to be written to the INI file
//! at times other than assignment if necessary.
//!
//! Example:
//! INI_AUTO<COLOR> m_Color;
//! In container constructor's initializer list:
//! m_Color(COLOR::RED),
template <class _DT> class INI_AUTO {

   public:

      INI_AUTO (
         const char *field,            //!< Field that the data is to be stored under
         const char *group = NULL,     //!< Group to locate field in, uses GetAppName() if NULL
         bool copyfield = false,       //!< Keep internal copy
         bool copygroup = false        //!< Keep internal copy
         ) :
         m_Group(group),
         m_Field(field),
         m_CopyGroup(copygroup),
         m_CopyField(copyfield)
         {
         if (copyfield) m_Field = strdup(field);
         if (copygroup) m_Group = strdup(group);
         IniRead(NULL, m_Group, m_Field, m_Data);
         }

      INI_AUTO (
         const _DT &defaultdata,             //!< Default value
         const char *field,            //!< Field that the data is to be stored under
         const char *group = NULL,     //!< Group to locate field in, uses GetAppName() if NULL
         bool copyfield = false,       //!< Keep internal copy
         bool copygroup = false        //!< Keep internal copy
         ) :
         m_Data(defaultdata),
         m_Group(group),
         m_Field(field),
         m_CopyGroup(copygroup),
         m_CopyField(copyfield)
         {
         if (copyfield) m_Field = strdup(field);
         if (copygroup) m_Group = strdup(group);
         IniRead(NULL, m_Group, m_Field, m_Data);
         }

      ~INI_AUTO (
         ) {
         if (m_CopyField) free(const_cast<char*>(m_Field));
         if (m_CopyGroup) free(const_cast<char*>(m_Group));
         }

      operator const _DT& (
         ) const { return (m_Data); }

      const _DT& operator= (
         const _DT& dt
         ) {
         m_Data = dt;
         Write();
         return (m_Data);
         }

      //! Alternative to assignment - allows setting of
      //! data without writing to file
      void Set (
         const _DT& dt,
         bool write = true
         ) {
         m_Data = dt;
         if (write)
            Write();
         }

      //! Force write to file
      void Write (
         INIHANDLE inihandle = NULL
         ) const { IniWrite(inihandle, m_Group, m_Field, m_Data); }           

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      _DT m_Data;
      const char *m_Group;             //!< Group to locate field in, uses GetAppName() if NULL
      const char *m_Field;             //!< Field that the data is to be stored under
      bool m_CopyGroup;                //!< Internal copy (free m_Group)
      bool m_CopyField;                //!< Internal copy (free m_Field)
      #endif // GENERATING_DOXYGEN_OUTPUT
   };

//! INI_AUTO_ENUM is a class designed to automatically handle reading and writing of
//! enum data from an INI file and ensure that IniReadEnum \ IniWrite pairs function
//! together correctly.  The constructor calls IniReadEnum and the assignment operator calls
//! IniWrite.  The Write method allows the data to be written to the INI file
//! at times other than assignment.
//!
//! Example:
//!   enum COLORTYPE {...};
//! INI_AUTO_ENUM<COLORTYPE> m_ColorType;
//! In container constructor's initializer list:
//! m_ColorType(COLORTYPE_Default),
template <class _DT> class INI_AUTO_ENUM {

   public:

      INI_AUTO_ENUM (
         const char *field,            //!< Field that the data is to be stored under
         const char *group = NULL,     //!< Group to locate field in, uses GetAppName() if NULL
         bool copyfield = false,       //!< Keep internal copy
         bool copygroup = false        //!< Keep internal copy
         ) :
         m_Data(data),
         m_Group(group),
         m_Field(field),
         m_CopyGroup(copygroup),
         m_CopyField(copyfield)
         {
         if (copyfield) m_Field = strdup(field);
         if (copygroup) m_Group = strdup(group);
         IniReadEnum(NULL, m_Group, m_Field, m_Data);
         }

      INI_AUTO_ENUM (
         const _DT &defaultdata,             //!< Default value
         const char *field,            //!< Field that the data is to be stored under
         const char *group = NULL,     //!< Group to locate field in, uses GetAppName() if NULL
         bool copyfield = false,       //!< Keep internal copy
         bool copygroup = false        //!< Keep internal copy
         ) :
         m_Data(defaultdata),
         m_Group(group),
         m_Field(field),
         m_CopyGroup(copygroup),
         m_CopyField(copyfield)
         {
         if (copyfield) m_Field = strdup(field);
         if (copygroup) m_Group = strdup(group);
         IniReadEnum(NULL, m_Group, m_Field, m_Data);
         }

      ~INI_AUTO_ENUM (
         ) {
         if (m_CopyField) free(const_cast<char*>(m_Field));
         if (m_CopyGroup) free(const_cast<char*>(m_Group));
         }

      operator const _DT& (
         ) const { return (m_Data); }

      const _DT& operator= (
         const _DT& dt
         ) {
         m_Data = dt;
         Write();
         return (m_Data);
         }

      //! Alternative to assignment - allows setting of
      //! data without writing to file
      void Set (
         const _DT& dt,
         bool write = true
         ) {
         m_Data = dt;
         if (write)
            Write();
         }

      //! Force write to file
      void Write (
         INIHANDLE inihandle = NULL
         ) const { IniWrite(inihandle, m_Group, m_Field, m_Data); }           

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

      _DT m_Data;
      const char *m_Group;             //!< Group to locate field in, uses GetAppName() if NULL
      const char *m_Field;             //!< Field that the data is to be stored under
      bool m_CopyGroup;                //!< Internal copy (free m_Group)
      bool