mi32/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.77 2009/09/25 13:26:00 mju Exp $
 *
 * $Log: inidefns.h_v $
 * Revision 1.77  2009/09/25 13:26:00  mju
 * Doc return value from IniRead.
 *
 * Revision 1.76  2007/02/20 18:43:24  scowan
 * Added flag for open and flush function.
 *
 * Revision 1.75  2006/10/05 20:37:22  mju
 * Move point/color read/write fns to own hdrs and don't include from here.
 *
 * Revision 1.74  2006/09/26 12:46:06  mju
 * Move ini_auto defns to own hdr.
 *
 * Revision 1.73  2006/09/25 16:41:33  mju
 * Move base types and low-level fns to inibase hdr.
 * Move inihnd class to own header (not included).
 *
 * Revision 1.72  2006/03/13 15:59:04  mju
 * Check ptrs_are_64_bit for mgui::id.
 * Check !longs_are_64_bit for long read/write.
 *
 * Revision 1.71  2006/02/09 20:46:45  dwilliss
 * include mi32/string.h so will compile in isolation
 *
 * Revision 1.70  2006/02/08 21:00:30  dwilliss
 * ifdefd out a ctor that doesn't compile under g++ 4.0 (and looks like it
 * would never work under any compiler if you actually tried to use it)
 *
 * Revision 1.69  2005/03/31 16:57:13  fileserver!dwilliss
 * Rename one of our types to MIUNICODE because it conflicted with a Microsoft #define
 *
 * Revision 1.68  2005/03/15 21:36:09  mju
 * Remove mapprojparm fns.
 *
 * 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.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'
 *
 * 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_INIBASE_H
   #include <mi32/inibase.h>
#endif

#ifndef  INC_MI32_STRING_H
   #include <mi32/string.h>
#endif

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


class FILEPATH;


#define INIFILE_Standard      "tntproc.ini"
#define INIFILE_Host          "tnthost.ini"

#define INIFLAG_None             0
#define INIFLAG_WriteRequired    0x00000002     
#define INIFLAG_ReadOnly         0x00000004     
#define INIFLAG_NoFlushOnWrite   0x00000008     
#define INIFLAG_InternalOnly     0x00000010     

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

extern "C" {


LIBEXPORT void IniClose (
   INIHANDLE iniptr                    
   );

LIBEXPORT int IniDeleteField (
   INIHANDLE iniptr,                   
   const char* group,                  
   const char* field                   
   );

LIBEXPORT int IniDeleteGroup (
   INIHANDLE iniptr,                   
   const char* group                   
   );

LIBEXPORT ERRVALUE IniFlush (
   INIHANDLE iniptr                 
   );

LIBEXPORT int IniGetBuffer (
   INIHANDLE iniptr,                   
   MIUNICODE **buffer                     
   );

LIBEXPORT const FILEPATH& IniGetFilePath (
   INIHANDLE inihandle
   );

LIBEXPORT int IniIsWritable (
   INIHANDLE iniptr                    
   );

LIBEXPORT ERRVALUE IniListAdd (
   const FILEPATH& filepath
   );

LIBEXPORT void IniListClear (
   );


LIBEXPORT int IniOpen (
   const char *basefilename,           
   INIHANDLE *iniptr,                  
   UINT32 flags = INIFLAG_None         
   );

LIBEXPORT void IniSetAppName (
   const char *AppName
   );

LIBEXPORT int IniSetBuffer (
   INIHANDLE iniptr,                   
   MIUNICODE *buffer                   
   );

LIBEXPORT int IniWriteBoolean (
   INIHANDLE iniptr,                   
   const char *group,                  
   const char *field,                  
   int value                           
   );

}  // Extern "C"

LIBEXPORT ERRVALUE IniOpen (
   const FILEPATH& filepath,           
   INIHANDLE *iniptr,                  
   UINT32 flags = INIFLAG_None
   );

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

#if defined(MISYSTEMDLL)

extern "C" {

LIBEXPORT INT32 IniReadString (
   INIHANDLE iniptr,                   
   const char* group,                  
   const char*const field,             
   UINT32 initype,                     
   void *data,                         
   INT32 len                           
   );

LIBEXPORT INT32 IniReadStringAlloc (
   INIHANDLE iniptr,                   
   const char* group,                  
   const char*const field,             
   void **data,                        
   UINT32 initype                      
   );

LIBEXPORT INT32 IniReadStringAllocML (
   INIHANDLE iniptr,                   
   const char* group,                  
   const char*const field,             
   UINT32 initype,                     
   void **data                         
   );

LIBEXPORT int IniWriteString (
   INIHANDLE iniptr,                   
   const char *group,                  
   const char *field,                  
   UINT32 initype,                     
   const void *data                    
   );

LIBEXPORT int IniWriteStringML (
   INIHANDLE iniptr,                   
   const char *group,                  
   const char *field,                  
   UINT32 initype,                     
   const void *data                    
   );

}  // Extern "C"

#endif

#endif // GENERATING_DOXYGEN_OUTPUT

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

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, bool& value) { return (_iniRead(hdl,group,field,INITYPE_Bool,&value,1)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, bool& value, bool dft) { value = dft; return (IniRead(hdl,group,field,value)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, INT8& value) { return (_iniRead(hdl,group,field,INITYPE_INT8,&value,1)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, INT8& value, INT8 dft) { value = dft; return (IniRead(hdl,group,field,value)); }

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); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UINT8& value) { return (_iniRead(hdl,group,field,INITYPE_UINT8,&value,1)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UINT8& value, UINT8 dft) { value = dft; return (IniRead(hdl,group,field,value)); }

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); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, INT16& value) { return (_iniRead(hdl,group,field,INITYPE_INT16,&value,1)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, INT16& value, INT16 dft) { value = dft; return (IniRead(hdl,group,field,value)); }

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); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UINT16& value) { return (_iniRead(hdl,group,field,INITYPE_UINT16,&value,1)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, UINT16& value, UINT16 dft) { value = dft; return (IniRead(hdl,group,field,value)); }

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); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, int& value) { return (_iniRead(hdl,group,field,INITYPE_INT32,&value,1)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, int& value, int dft) { value = dft; return (IniRead(hdl,group,field,value)); }

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); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, unsigned int& value) { return (_iniRead(hdl,group,field,INITYPE_UINT32,&value,1)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, unsigned int& value, unsigned int dft) { value = dft; return (IniRead(hdl,group,field,value)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, unsigned int& value, unsigned int dft, unsigned int min, unsigned int 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(LONGS_ARE_64_BIT)      // longs are 32-bit

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, long& value) { return (_iniRead(hdl,group,field,INITYPE_INT32,&value,1)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, long& value, long dft) { value = dft; return (IniRead(hdl,group,field,value)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, long& value, long dft, long min, long max) { value = dft; int err = IniRead(hdl,group,field,value); if (value < min) value = min; else if (value > max) value = max; return (err); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, unsigned long& value) { return (_iniRead(hdl,group,field,INITYPE_UINT32,&value,1)); }

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)); }

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; int err = IniRead(hdl,group,field,value); if (value < min) value = min; else if (value > max) value = max; return (err); }

#endif   // longs are 32-bit

#if defined(PTRS_ARE_64_BIT)

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, MGUI::ID& value) { int temp = static_cast<int>(value); int result = IniRead(hdl,group,field,temp); value = temp; return (result); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, MGUI::ID& value, MGUI::ID dft) { value = dft; return (IniRead(hdl,group,field,value)); }

#endif

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, float& value) { return (_iniRead(hdl,group,field,INITYPE_Float,&value,1)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, float& value, float dft) { value = dft; return (IniRead(hdl,group,field,value)); }

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); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, double& value) { return (_iniRead(hdl,group,field,INITYPE_Double,&value,1)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, double& value, double dft) { value = dft; return (IniRead(hdl,group,field,value)); }

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); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, char *str, int size) { return (_iniReadString(hdl,group,field,INITYPE_ASCII,str,size)); }

inline int IniRead (INIHANDLE hdl, const char *group, const char *field, MIUNICODE *str, int size) { return (_iniReadString(hdl,group,field,INITYPE_Unicode,str,size)); }

inline bool IniReadBoolean (INIHANDLE hdl, const char *group, const char *field, bool dft) { bool value; IniRead(hdl,group,field,value,dft); return (value); }

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);
   }

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);
   }

inline int IniReadStringMultiLine (
   INIHANDLE iniptr,                   
   const char *group,                  
   const char *field,                  
   char*& string                       
   ) {
   return (_iniReadStringAllocML(iniptr,group,field,INITYPE_ASCII,reinterpret_cast<void**>(&string)));
   }

inline int IniReadStringMultiLine (
   INIHANDLE iniptr,                   
   const char *group,                  
   const char *field,                  
   MIUNICODE*& string                     
   ) {
   return (_iniReadStringAllocML(iniptr,group,field,INITYPE_Unicode,reinterpret_cast<void**>(&string)));
   }

inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, const bool& value) { return (IniWriteBoolean(hdl,group,field,value)); }

inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, int value) { return (_iniWrite(hdl,group,field,INITYPE_INT32,&value,1)); }

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(LONGS_ARE_64_BIT)      // longs are 32-bit

inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, long value) { return (_iniWrite(hdl,group,field,INITYPE_INT32,&value,1)); }

inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, unsigned long value) { return (_iniWrite(hdl,group,field,INITYPE_UINT32,&value,1)); }

#endif   // longs are 32-bit

#if defined(PTRS_ARE_64_BIT)

inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, MGUI::ID value) { return (IniWrite(hdl,group,field,static_cast<int>(value))); }

#endif

inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, double value) { return (_iniWrite(hdl,group,field,INITYPE_Double,&value,1)); }

inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, const char *str) { return (_iniWriteString(hdl,group,field,INITYPE_ASCII,str)); }

inline int IniWrite (INIHANDLE hdl, const char *group, const char *field, const MIUNICODE *str) { return (_iniWriteString(hdl,group,field,INITYPE_Unicode,str)); }

inline int IniWriteStringMultiLine (
   INIHANDLE iniptr,                   
   const char *group,                  
   const char *field,                  
   const char *string                  
   ) {
   return (_iniWriteStringML(iniptr,group,field,INITYPE_ASCII,string));
   }

inline int IniWriteStringMultiLine (
   INIHANDLE iniptr,                   
   const char *group,                  
   const char *field,                  
   const MIUNICODE *string             
   ) {
   return (_iniWriteStringML(iniptr,group,field,INITYPE_Unicode,string));
   }


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


#undef LIBEXPORT

#endif      // INC_MI32_INIDEFNS_H

---