serializ.h

Go to the documentation of this file.

/**
 * \file serializ.h <mi32/serializ.h>
 * \brief SERIALIZER class definition
 *
 * \if NODOC
 * $Id: serializ.h_v 1.39 2004/10/01 17:21:10 mju Exp $
 *
 * $Log: serializ.h_v $
 * Revision 1.39  2004/10/01 17:21:10  mju
 * Add getItemValue as double.
 *
 * Revision 1.38  2004/06/30 18:46:12  mju
 * Remove type_mapprojparm.
 *
 * Revision 1.37  2004/06/28 17:55:41  mju
 * Add spaterf and region2d support.
 *
 * Revision 1.36  2004/06/25 16:31:15  mju
 * Add itemdefs for coordrefsys.
 *
 * Revision 1.35  2004/03/01 18:38:56  mju
 * Disable deprecated declaration warning within header.
 *
 * Revision 1.34  2003/11/12 20:54:05  mju
 * Add logging methods.
 *
 * Revision 1.33  2003/09/26 19:36:41  scowan
 * Removed use of include file.
 *
 * Revision 1.32  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.31  2003/09/09 16:22:57  mju
 * Add GetFilePath.
 *
 * Revision 1.30  2003/03/10 15:43:14  mju
 * nc.
 *
 * Revision 1.29  2002/09/11 18:00:39  mju
 * Add ITEM_RVCOBJITEM...
 *
 * Revision 1.28  2002/08/21 20:40:04  scowan
 * Deprecate old object name define.
 *
 * Revision 1.27  2002/04/04 18:36:24  mju
 * Remove vararg method as not used.
 *
 * Revision 1.26  2002/04/04 18:25:12  mju
 * Add TYPE_RVCOBJECTNAME.
 * Deprecate varargs method.
 *
 * Revision 1.25  2002/03/26 21:12:56  mju
 * Remove deprecated methods.
 *
 * Revision 1.24  2002/03/05 14:37:01  mju
 * Make PutItem methods public.
 *
 * Revision 1.23  2002/03/04 18:45:39  mju
 * Add Open() using objitem.
 *
 * Revision 1.22  2001/12/28 21:35:49  mju
 * SerialWrite and related methods now const.
 *
 * Revision 1.21  2001/07/12 17:30:32  dwilliss
 * Allow for new TYPE_StringMLRaw -- When writing to text file, don't muck
 * with the encoding.  It's just a raw one-byte-character string who's encoding
 * is only known by the caller.  Can't assume it's UTF8
 *
 * Revision 1.20  2001/07/12 15:55:19  dwilliss
 * Made PutStr() methods public (just the Unicode ones).  There was a comment
 * on the (char*) ones to make them go away, so I left them private.  All the
 * PutDouble, PutInt, PutUnsigned methods were already public, so why not
 * the string ones?
 *
 * Revision 1.19  2001/06/07 16:09:36  mju
 * Add details for SERIALIZABLE.
 * Remove unnecessary SERIALIZABLE methods.
 * Add TYPE_SERIALIZABLE/PTR.
 *
 * Revision 1.18  2001/03/05 21:43:59  mju
 * Add StatusTextUpdate.
 *
 * Revision 1.17  2000/11/30 20:36:04  mju
 * Add Rewind().
 *
 * Revision 1.16  2000/11/13 15:00:31  mju
 * Change formula layer to use new geoformula class.
 *
 * Revision 1.14  2000/09/20 14:05:03  mju
 * Add flag to not prompt for missing linked file.
 *
 * Revision 1.13  2000/08/23 22:19:16  dwilliss
 * MISTRING?
 *
 * Revision 1.12  2000/08/18 20:08:09  dwilliss
 * Added LPOINT2D/LRECT2D support
 *
 * Revision 1.9  2000/03/08 18:28:05  mju
 * Add GetIgnoreSkippable() method.
 *
 * Revision 1.8  2000/03/03 15:03:07  mju
 * Add FLAG_AddOffsetCB.
 *
 * Revision 1.7  2000/02/15 14:21:46  mju
 * Make SkipStruct public.
 *
 * Revision 1.6  2000/01/27 15:33:40  mju
 * Add GetObjectName().
 *
 * Revision 1.5  2000/01/19 18:50:49  mju
 * Allow FILEPATH for Make/Open.
 *
 * Revision 1.4  2000/01/19 14:22:29  mju
 * Make PutDouble/PutInt public.
 * Add GetItemValue().
 *
 * Revision 1.3  1999/12/10 23:07:25  mju
 * Make SERIALIZABLE pure virtual.
 *
 * Revision 1.1  1999/12/02 23:21:26  mju
 * Initial revision
 *
 * \endif
**/

#ifndef  INC_MI32_SERIALIZ_H
#define  INC_MI32_SERIALIZ_H

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

#ifndef  INC_MI32_RVCDEFNS_H
#include <mi32/rvcdefns.h>
#endif

#ifndef  INC_MI32_MSTATUS_H
#include <mi32/mstatus.h>
#endif

#ifdef WIN32
#pragma warning (disable:4996)   // Disable warning about deprecated declaration within header
#endif

//! Forward declarations

class SERIALIZABLE;
struct RVCPARMINFO;
struct OLDPROJPARM;
struct COLOR;
struct DPOINT2D;
struct DPOINT3D;
struct DRECT2D;
struct DRECT3D;
namespace SPATREF {
   class COORDREFSYS;
   }

//-----------------------------------------------------------------------------
//    SERIALIZER class
//-----------------------------------------------------------------------------

//! Class for storing object instances to file.
//! The SERIALIZER class provides methods to write object instances to a text
//! file/object and read those instances back into memory later.  The design
//! allows for the object structure to change while maintaining compatibility
//! with previously existing files.

class SERIALIZER {
   public:

      //! Item definition for single member of structure or class.
      class ITEMDEF {
         public:

            //! Item types.
            enum TYPE {
               TYPE_End =              0,

               //! Scalars
               TYPE_UINT8 =            1,
               TYPE_INT8 =             2,
               TYPE_UINT16 =           3,
               TYPE_INT16 =            4,
               TYPE_UINT32 =           5,
               TYPE_INT32 =            6,
               TYPE_BitUINT32 =        7,    //!< Bit value in UINT32, bit specified in .extra
               TYPE_UInt =             8,    //!< unsigned int
               TYPE_Int =              9,    //!< int
               TYPE_Float =            10,   //!< float
               TYPE_Double =           11,   //!< double
               TYPE_Bool =             12,   //!< bool
               TYPE_UINT8_Array =      13,
               TYPE_Enum =             14,   //!< enum, size specified in .extra

               //! Strings
               TYPE_StringU =          20,   //!< UNICODE string (.extra contains size)
               TYPE_MISTRING =         21,   //!< MISTRING
               TYPE_MISTRING_ML =      22,   //!< Multi-line MISTRING
               TYPE_StringMLU =        23,   //!< Multi-line Unicode string
               TYPE_StringPtrU =       24,   //!< Pointer to Unicode string
               TYPE_StringA =          25,   //!< ASCII string (.extra contains size)
               TYPE_StringMLA =        26,   //!< Multi-line ASCII string (pointer)
               TYPE_StringPtrA =       27,   //!< Multi-line Unicode String (pointer)
               TYPE_StringMLRaw =      28,   //!< Multi-line raw (char*) string (pointer)

               //! Files and objects
               TYPE_FileName =         30,   //!< UNICODE filename
               TYPE_FILEPATH =         31,
               TYPE_Object =           32,   //!< RVC object, type stored in ITEMDEF.extra
               TYPE_SubObject =        33,   //!< Subobject, use previous TYPE_Object as parent
               TYPE_RVCOBJECTNAME =    34,   //!< RVC::OBJECTNAME
               TYPE_RVCOBJITEMFILE =   35,   //!< FilePath portion of RVC::OBJITEM
               TYPE_RVCOBJITEMOBJECT = 36,   //!< Object portion of RVC::OBJITEM, type stored in ITEMDEF.extra

               //! Generic
               TYPE_Special =          40,   //!< Use cbfunc to do read and write
               TYPE_SpecialPtr =       41,   //!< Use cbfunc to do read and write
               TYPE_Struct =           42,   //!< Structure/class
               TYPE_StructPtr =        43,   //!< Structure/class pointer, will be allocated if 0, .extra contains size
               TYPE_StructPtrArray =   44,   //!< Array of structure pointers, .extra contain size

               //! Built-in structures
               TYPE_COLOR =            50,   //!< COLOR
               TYPE_DRECT2D =          51,   //!< DRECT2D
               TYPE_DPOINT2D =         52,   //!< DPOINT2D
               TYPE_DPOINT3D =         53,   //!< DPOINT3D
               TYPE_POINTSTYLE =       55,   //!< POINTSTYLE
               TYPE_LINESTYLE =        56,   //!< LINESTYLE
               TYPE_POLYSTYLE =        57,   //!< POLYSTYLE
               TYPE_TEXTSTYLE =        58,   //!< TEXTSTYLE
               TYPE_LPOINT2D =         59,   //!< LPOINT2D
               TYPE_LRECT2D =          60,   //!< LRECT2D
               TYPE_OLDPROJPARMTOCRS = 61,   //!< Serialized as OLDPROJPARM, in memory as SPATREF::COORDREFSYS
               TYPE_COORDREFSYS =      62,   //!< SPATREF::COORDREFSYS
               TYPE_REGION2D =         63,   //!< REGION2D
               TYPE_DRECT3D =          64,   //!< DRECT3D

               TYPE_SERIALIZABLE =     90,   //!< SERIALIZABLE object
               TYPE_SERIALIZABLEPTR =  91,   //!< Pointer to SERIALIZABLE object

               TYPE_InternalSer =      998,
               TYPE_Start =            999   //!< Used internally to start new structure
               };

            enum FLAGS {
               FLAG_None =                0x0000,
               FLAG_NoWrite0 =            0x0001,  //!< Don't write value if not set
               FLAG_NoWrite =             0x0002,  //!< Don't write this item
               FLAG_NoRead =              0x0004,  //!< Don't read this item
               FLAG_FileNoExist0 =        0x0008,  //!< When reading PARMITEM_FileName zero string if file doesn't exist
               FLAG_Skippable =           0x0020,  //!< Item will be ignored if "IgnoreSkippable" set
               FLAG_AddOffsetCB =         0x0040,  //!< Add offset to pointer when passing to callback function
               FLAG_FindFileImmed =       0x0080,  //!< Search for file immediately instead of waiting until looking for object
               FLAG_DontAskLinkFile =     0x0100   //!< Don't prompt user if can't find linked file
               };

            enum ACTION {
               ACTION_None =           0x0000,
               ACTION_ReadBegin =      0x0001,
               ACTION_ReadEnd =        0x0002,
               ACTION_WriteBegin =     0x0004,
               ACTION_WriteEnd =       0x0008,
               ACTION_Read =           0x0010,
               ACTION_Write =          0x0020
               };

            typedef ERRVALUE (*CBFUNC)(SERIALIZER&, const ITEMDEF*, void *data, ACTION action);

            char *name;                      //!< Name of the item, 0 to terminate array, not case-sensitive
            TYPE type;                       //!< Item type
            int offset;                      //!< Offset into class/struct
            int extra;                       //!< Extra type-specific data, see below
            const ITEMDEF *substruct;        //!< Sub-structure definition for TYPE_Struct/StructPtr
            FLAGS flags;                     //!< Flags
            CBFUNC cbfunc;                   //!< Callback function for this item

            //!   The meaning of the "extra" field is dependent on the "type" field:
            //!
            //!      "type"
            //!      UINT8_Array                Number of array entries
            //!      StringA, StringU           Number of bytes in entry (use membersize in definition)
            //!      Object, SubObject          Object type (0 for OTYPE_ALL)
            //!      BitUINT32                  Bit number to use, 0 = lowest
            //!      StructPtr, StructPtrArray  Size of structure to allocate
            //!      Enum                       Size of member

            //! When handling TYPE_Special items, the cbfunc will be called with ACTION_Read or
            //! ACTION_Write.  The cbfunc is responsible for actually reading and writing the data
            //! using the SERIALIZER class reference provided.

         };

      //! Merge two item definition arrays.
      //! This is useful when inheriting from a class which already uses an item definition array.
      static ITEMDEF* MergeItemDef (
         const ITEMDEF *def1,             //!< First definition array
         const ITEMDEF *def2              //!< Second definition array
         );                               //! Returns new allocated definition array

      //! Default constructor.
      SERIALIZER (
         );

      //! Destructor.
      virtual ~SERIALIZER (
         );

      //! Close the serializer, will be done in destructor.
      void Close (
         );

      //! Get path to serialization file.
      const FILEPATH& GetFilePath (
         ) const { return (m_filepath); }

      //! Determine if ignoring "skippable" items.
      bool GetIgnoreSkippable (
         ) const { return (m_IgnoreSkippable); }

      //! Get name of current item being read/written.
      const char* GetItemName (
         ) const { return (m_itemname); }

      //! Get value for current item being read.
      const UNICODE* GetItemValue (
         ) const { return (m_parmvalue); }

      //! Get value for current item as double.
      //! @return true if could convert, false if not
      bool GetItemValue (
         double& value                    //!< Value returned
         ) const;

      // Get log text.
      const MISTRING& GetLog (
         ) const { return (m_Log); }

      // Get log text (non-const).
      MISTRING& GetLog (
         ) { return (m_Log); }

      //! Get name of object, will be blank if text file.
      const UNICODE* GetObjectName (
         ) const { return (m_objname); }

      //! Get list of missing files/objects after scan, also clears the list.
      FNAMEINODEUC* GetScanListMissing (
         ) {
         FNAMEINODEUC *temp = m_ScanFileObjListMissing;
         m_ScanFileObjListMissing = NULL;
         return (temp);
         }

      //! Get list of "used" files/objects after scan, also clears the list.
      FNAMEINODEUC* GetScanListUsed (
         ) {
         FNAMEINODEUC *temp = m_ScanFileObjListUsed;
         m_ScanFileObjListUsed = NULL;
         return (temp);
         }

      //! Get current version setting.
      UINT16 GetVersion (
         ) const { return (m_Version[m_depth]); }

      //! Check if scanning serialization only.
      bool IsScanOnly (
         ) const { return (m_ScanOnly); }

      //! Clear serialization log.
      void LogClear (
         ) { m_Log.Clear(); }

      //! Add error message to log.
      //! Will insert newline before and after error text.
      void LogError (
         ERRVALUE err
         );

      //! Add text to log.
      void LogText (
         const MISTRING& text
         ) { m_Log << text; }

      //! Create object to contain serialization.
      ERRVALUE Make (
         const FILEPATH& filepath,        //!< RVC file path
         RVCPARMINFO& objinfo             //!< New or existing object header
         );

      //! Create object to contain serialization.
      ERRVALUE Make (
         int fhandle,                     //!< RVC file handle
         RVCPARMINFO& objinfo             //!< New or existing object header
         );

      //! Create text file to contain serialization.
      ERRVALUE Make (
         const FILEPATH& filepath,        //!< Text file path
         int version = 1                  //!< Version to write
         );

      //! Open object containing serialization to read.
      ERRVALUE Open (
         const RVC::OBJITEM& objitem      //!< RVC object item reference
         );

      //! Open object containing serialization to read.
      ERRVALUE Open (
         const FILEPATH& filepath,        //!< RVC file path
         INT32 inode,                     //!< RVC object inode
         RVCPARMINFO& objinfo             //!< Object header returned
         );

      //! Open object containing serialization to read.
      ERRVALUE Open (
         int fhandle,                     //!< Open RVC file handle
         INT32 inode,                     //!< RVC object inode
         RVCPARMINFO& objinfo             //!< Object header returned
         );

      //! Open text file containing serialization to read.
      ERRVALUE Open (
         const FILEPATH& filepath         //!< Text file path
         );

      //! Write beginning tag for starting a component.
      ERRVALUE PutBegin (
         const char *tagname,             //!< Tag name to write
         UINT16 version = 0               //!< Optional version
         );

      //! Write floating-point value.
      ERRVALUE PutDouble (
         const char *tagname,             //!< Tag name
         double value                     //!< Value to write
         );

      //! Write ending tag at end of a component.
      ERRVALUE PutEnd (
         );

      //! Write integer value.
      ERRVALUE PutInt (
         const char *tagname,             //!< Tag name to write
         int value                        //!< Value to write
         );

      //! Write COLOR item.
      ERRVALUE PutItem (
         const char *tagname,             //!< Tag name to write
         const COLOR& color               //!< Item value
         );

      //! Write DPOINT2D item.
      ERRVALUE PutItem (
         const char *tagname,             //!< Tag name to write
         const DPOINT2D& point2d          //!< Item value
         );

      //! Write DPOINT3D item.
      ERRVALUE PutItem (
         const char *tagname,             //!< Tag name to write
         const DPOINT3D& point3d          //!< Item value
         );

      //! Write DRECT2D item.
      ERRVALUE PutItem (
         const char *tagname,             //!< Tag name to write
         const DRECT2D& rect              //!< Item value
         );

      //! Write DRECT3D item.
      ERRVALUE PutItem (
         const char *tagname,             //!< Tag name to write
         const DRECT3D& rect              //!< Item value
         );

      //! Write LPOINT2D item.
      ERRVALUE PutItem (
         const char *tagname,             //!< Tag name to write
         const LPOINT2D& point2d          //!< Item value
         );

      //! Write LRECT2D item.
      ERRVALUE PutItem (
         const char *tagname,             //!< Tag name to write
         const LRECT2D& rect              //!< Item value
         );

      //! Write OLDPROJPARM item.
      ERRVALUE PutItem (
         const char *tagname,             //!< Tag name to write
         const OLDPROJPARM& oldprojparm   //!< Item value
         );

      //! Write SPATREF::COORDREFSYS item.
      ERRVALUE PutItem (
         const char *tagname,             //!< Tag name to write
         const SPATREF::COORDREFSYS& crs  //!< Item value
         );

      //! Write a single-line Unicode string
      ERRVALUE PutStr (
         const char *tagname,             //!< Tag name to write
         const UNICODE *str               //!< String
         );

      //! Write a Multi-line Unicode String
      ERRVALUE PutStrML (
         const char *tagname,             //!< Tag name to write
         const UNICODE *str               //!< String
         );

      //! Write unsigned integer value.
      ERRVALUE PutUnsigned (
         const char *tagname,             //!< Tag name to write
         unsigned int value               //!< Item value
         );

      //! Read SERIALIZABLE object.
      inline ERRVALUE Read (
         SERIALIZABLE& object             //!< Object to read
         );

      //! Read SERIALIZABLE object.
      ERRVALUE Read (
         const char *tagname,             //!< Tag name to match
         SERIALIZABLE& object             //!< Object to read
         );

      //! Read items from serialization.
      ERRVALUE Read (
         const ITEMDEF *itemdef,          //!< Item definition array
         void *data                       //!< Serialization data
         );

      //! Read items from serialization.
      ERRVALUE Read (
         const char *tagname,             //!< Tag name to match
         const ITEMDEF *itemdef,          //!< Item definition array
         void *data                       //!< Serialization data
         );

      //! Read OLDPROJPARM from serialization.
      ERRVALUE Read (
         OLDPROJPARM& oldprojparm
         );

      //! Rewind file to beginning.
      ERRVALUE Rewind (
         );

      //! Set whether to ignore "skippable" items.
      void SetIgnoreSkippable (
         bool IgnoreSkippable = true      //!< Ignore skippable mode
         ) { m_IgnoreSkippable = IgnoreSkippable; }

      //! Set scan-only mode.
      void SetScanOnly (
         bool ScanOnly                    //!< Scan only mode
         ) { m_ScanOnly = ScanOnly; }

      //! Set version (for overriding).
      void SetVersion (
         UINT16 Version                   //!< Version
         ) { m_Version[m_depth] = Version; }

      //! Skip remainder of current structure (for use in item callback).
      ERRVALUE SkipStruct (
         );

      //! Update status text from Unicode string.
      ERRVALUE StatusTextUpdate (
         const UNICODE *string
         ) { return (MstatusTextUpdateString(m_StatusContext,0,string)); }

      //! Write items without begin/end tags.
      ERRVALUE Write (
         const ITEMDEF *itemdef,          //!< Item definition array
         const void *data                 //!< Data to write
         );

      //! Write items to serialized output.
      ERRVALUE Write (
         const char *tagname,             //!< Name to tag object with
         const ITEMDEF *itemdef,          //!< Item definition array
         const void *data,                //!< Data to write
         UINT16 version = 0               //!< Version to set if top level object
         );

      //! Write SERIALIZABLE object.
      inline ERRVALUE Write (
         const SERIALIZABLE& object,      //!< Object to write
         const char *tagname = 0          //!< Name to tag object with
         );

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

      FILEPATH m_filepath;                //!< Path to file
      RVC::OBJECTNAME m_objname;          //!< Name of object if in RVC file
      FILE *m_fp;                         //!< Text file handle if non-RVC
      int m_fhandle;                      //!< RVC file handle if Text object
      int m_ohandle;                      //!< RVC object handle for Text object
      int m_depth;                        //!< Current depth
      UINT16 m_Version[128];              //!< Version at current depth
      char m_itemname[128];
      UNICODE m_parmvalue[2048];          //!< Last parameter value
      MSTATUSCONTEXT m_StatusContext;
      INT32 m_filesize;                   //!< Size of file/object being read for status update
      INT32 m_filepos;                    //!< Position in file/object for status update
      bool m_IgnoreSkippable;
      bool m_ScanOnly;
      FNAMEINODEUC *m_ScanFileObjListUsed;
      FNAMEINODEUC *m_ScanFileObjListMissing;
      MISTRING m_Log;

      static const ITEMDEF* GetItemDefREGION2D (
         );

      static const ITEMDEF* GetItemDefSUBREGION2D (
         );

      //! Call callback for item if necessary.
      ERRVALUE CallItemCB (
         const ITEMDEF *itemdef,
         void *data,                      //!< Callback data
         ITEMDEF::ACTION action           //!< Callback action
         );

      //! Find link file, add to missing file list if can't find it.
      ERRVALUE FindLinkFile (
         const ITEMDEF *parmdp,
         const UINT8* data,
         FILEPATH& linkfilepath,
         UINT32 findflags = 0
         );

      //! Find object.
      int FindObject (
         const ITEMDEF *parmdp,
         const ITEMDEF *startdp,
         UINT8 *data
         );

      //! Find subobject.
      int FindSubObject (
         const ITEMDEF *parmdp,
         const ITEMDEF *startdp,
         UINT8 *data
         );

      //! Get multi-line string (Unicode).
      ERRVALUE GetStrML (
         UNICODE **str                    //!< XXX change to MISTRING&
         );

      //! Get multi-line string (ASCII or RAW).
      ERRVALUE GetStrML (
         char **str,
         bool raw = false  
         );

      //! 
      ERRVALUE PutObjName (
         const ITEMDEF *parmdp,
         const ITEMDEF *startdp,
         const UINT8 *data
         );

      //! 
      ERRVALUE PutStr (
         const char *tagname,
         const char *str                  //!< XXX eliminate
         );


      //! 
      ERRVALUE PutStrML (
         const char *tagname,
         const char *str
         );

      //! 
      ERRVALUE PutSubObjName (
         const ITEMDEF *parmdp,
         const ITEMDEF *startdp,
         const UINT8 *data
         );

      //! 
      ERRVALUE ReadLine (
         UNICODE *buf,                    //!< XXX change to MISTRING&
         int bufsize,
         bool raw = false
         );

      //! Write single-line UNICODE string.
      ERRVALUE WriteText (
         const UNICODE *str               //!< String to write
         );

      //! Write ASCII string.
      ERRVALUE WriteText (
         const char *str                  //!< String to write
         );

      SERIALIZER (const SERIALIZER&);
      SERIALIZER& operator= (const SERIALIZER&);
      #endif // GENERATING_DOXYGEN_OUTPUT
   };

DEFINE_ENUM_OPERATORS(SERIALIZER::ITEMDEF::FLAGS);
DEFINE_ENUM_OPERATORS(SERIALIZER::ITEMDEF::ACTION);


//-----------------------------------------------------------------------------
//    SERIALIZABLE interface definition
//-----------------------------------------------------------------------------

//! Interface class for making object serializable.
//! Objects may be serialized without inheriting from this interface provided
//! they are serialized as part of a container object.  In general there are two
//! reasons to inherit from SERIALIZABLE.
//!
//!      1. If the object will be a top-level item in the serialization.  This
//!         makes it easy to read and write the object via the SERIALIZER Read()
//!         and Write() methods pertaining to SERIALIZABLE objects.  Simple
//!         objects which may be represented by an ITEMDEF array do not need to
//!         be made serializable as there are Read/Write methods which may use
//!         this array.  The GRE_LAYOUT and GRE_GROUP classes are examples.
//!
//!      2. If an object is contained within another object and has complicated
//!         serialization which must be implemented via functions rather than
//!         using and ITEMDEF array.  This allows use of TYPE_SERIALIZABLE and
//!         TYPE_SERIALIZABLEPTR in the containing object's ITEMDEF array, thus
//!         simplifying its definition.  The GRE_LAYER::DISPPARM class is an
//!         example of this case.
//!
//!   By convention, if an object implements SerialRead and/or SerialWrite() the
//!   method signatures should match those used in SERIALIZABLE even if the class
//!   does not actually implement the SERIALIZABLE interface.  This allows easy
//!   modification should it become necessary to implement the interface in the
//!   future.  The GRE_LAYER class is an example of this case in that it defines
//! both SerialRead() and SerialWrite() methods but does not specifically
//! inherit from SERIALIZABLE.

class SERIALIZABLE {
   //! This is an "interface" class and must therefore
   //! only have virtual methods and no members.

   public:

      //! Read component from serialization.
      //! This method must be called only after the tag name has been read and
      //! is responsible for determining how to deserialize the component
      //! elements.  When beginning a deserialization, usually the
      //! SERIALIZER::Read(tagname,object) method should be used to match
      //! the desired tag name which was used in writing.
      //! A default implementation is not possible due to multiple inheritance
      //! resulting in a different "this" pointer being passed than the actual
      //! object, which causes the offset values in the ITEMDEF arrays to be wrong.
      virtual ERRVALUE SerialRead (
         SERIALIZER& serializer
         ) = 0;

      //! Write object to serialization.
      //! This method must write the tag name provided, using SERIALIZER::PutBegin().
      //! If the tagname is 0 (default) then it must determine the proper tag name to
      //! write.  After writing the object this method must write the ending tag using
      //! SERIALIZER::PutEnd().
      //! When inheriting this interface, the default value of 0 for the tag name
      //! must NOT be redefined.  (See Meyers, Effective C++, item #38)
      //! A default implementation is not possible due to multiple inheritance
      //! resulting in a different "this" pointer being passed than the actual
      //! object, which causes the offset values in the ITEMDEF arrays to be wrong.
      virtual ERRVALUE SerialWrite (
         SERIALIZER& serializer,
         const char *tagname = 0
         ) const = 0;
   };


//-----------------------------------------------------------------------------
//!      Inline methods
//-----------------------------------------------------------------------------

#ifndef GENERATING_DOXYGEN_OUTPUT

inline ERRVALUE SERIALIZER::Read (
   SERIALIZABLE& object
   ) {
   return (object.SerialRead(*this));
   }

inline ERRVALUE SERIALIZER::Write (
   const SERIALIZABLE& object,
   const char *tagname
   ) {
   return (object.SerialWrite(*this,tagname));
   }

#endif //!< GENERATING_DOXYGEN_OUTPUT

#ifdef WIN32
#pragma warning (default:4996)   // Restore warning about deprecated declaration
#endif

#endif   //!< INC_MI32_SERIALIZ_H

---