geocat.h

Go to the documentation of this file.

/**
 * \file geocat.h <mi32/geocat.h>
 * \brief Geographic Catalog (GEOCAT) class
 *
 * \if NODOC
 * $Id: geocat.h_v 1.14 2004/06/30 13:31:09 mju Exp $
 *
 * $Log: geocat.h_v $
 * Revision 1.14  2004/06/30 13:31:09  mju
 * Use spatref.
 *
 * Revision 1.13  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.12  2000/10/13 14:57:47  dwilliss
 * Must use "friend class NAME", not "friend NAME"
 *
 * Revision 1.11  2000/09/20 17:47:51  mju
 * Add GetProjection() static method.
 *
 * Revision 1.10  2000/09/13 17:08:28  mju
 * Add "findnow" flag to GetObject().
 * Add iterator::showprogress().
 *
 * Revision 1.9  2000/08/16 16:48:02  mju
 * *** empty log message ***
 *
 * Revision 1.8  2000/08/07 20:35:29  mju
 * Redesign to always use regions.
 *
 * Revision 1.5  2000/07/19 22:05:06  dwilliss
 * Constructors don't need a GEOCAT passed any more.
 *
 * Revision 1.4  2000/07/19 17:38:56  dwilliss
 * ScanDirectory() now takes an optional StatusContext
 *
 * Revision 1.3  2000/07/19 16:22:08  dwilliss
 * Implementation mostly done.  API nearly final
 *
 * Revision 1.1  2000/07/17 14:16:42  dwilliss
 * Initial revision
 * \endif
**/


#ifndef INC_MI32_GEOCAT_H
#define INC_MI32_GEOCAT_H

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

#ifndef INC_MI32_MISTRING_H
#include <mi32/mistring.h>
#endif

#ifndef INC_MI32_DATETIME_H
#include <mi32/datetime.h>
#endif

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

#ifndef INC_MI32_RECT_H
#include <mi32/rect.h>
#endif

#ifndef INC_MI32_POINT_H
#include <mi32/point.h>
#endif

#ifndef INC_MI32_REGION2D_H
#include <mi32/region2d.h>
#endif

#ifndef INC_MI32_RVCDBASE_H
#include <mi32/rvcdbase.h>
#endif

#ifndef INC_MI32_SIMPLEAR_H
#include <mi32/simplear.h>
#endif


class STATUSCONTEXT;

#ifndef GENERATING_DOXYGEN_OUTPUT
//! A class for keeping track of Database Cursors.
//! Should eventually be an RVC class that does the
//! same thing.
class GEOCAT_ITERATOR_CURSOR;    
#endif //!< GENERATING_DOXYGEN_OUTPUT

//! GeoSpatial Catalog class.
//!
//! This class handles a catalog file.
class GEOCAT {
   public:

      //! A file in the object catalog.
      class FILERECORD {
         public:

            //! Formats.  Only RVC for now.
            enum FORMAT {
               FORMAT_RVC= 0        //!< XXX Use defines from MIE instead
               };

            //! default constructor
            FILERECORD (
               );

            //! Copy constructor
            FILERECORD (
               const FILERECORD& rhs
               );

            //! Destructor
            ~FILERECORD (
               );

            //! Assignment from another FILERECORD
            FILERECORD& operator= (
               const FILERECORD& rhs
               );

            UINT32 GetFileID (
               ) const {
               return (m_ID);
               }

            //! Get the filename
            const FILEPATH& GetFilePath (
               ) const {
               return (m_filepath);
               }

            FORMAT GetFormat (
               ) const {
               return (m_Format);
               }

            FILEPATH::FILESYSTYPE GetMediaType (
               ) const {
               return (m_MediaType);
               }

            const DATETIME& GetTimeStamp (
               ) const {
               return (m_TimeStamp);
               }

            //! Set the filename.
            //! If the filepath passed in is relative, it's assumed to be
            //! relative to the catalog file.  
            void SetFilePath (
               const FILEPATH& filepath
               );

         private:
            #ifndef GENERATING_DOXYGEN_OUTPUT
            //! Used by GEOCAT::Write().
            void SetID (
               UINT32 id
               ) {
               m_ID = id;
               return;
               }

            //! Set timestamp, used by GEOCAT::Write().
            void SetTimeStamp (
               ) {
               time_t modtime;
               m_filepath.GetTimeModified(&modtime);
               m_TimeStamp = modtime;
               return;
               }

            UINT32 m_ID;
            FILEPATH m_filepath;
            DATETIME m_TimeStamp;
            FILEPATH::FILESYSTYPE m_MediaType;
            FORMAT m_Format;

            friend class GEOCAT;
            #endif // GENERATING_DOXYGEN_OUTPUT
         };


      //! An item in the object catalog.
      class OBJRECORD {
         public:

            //! Default constructor
            OBJRECORD (
               );

            //! Copy constructor
            OBJRECORD (
               const OBJRECORD& rhs
               );

            //! Destructor
            ~OBJRECORD (
               );

            //! Assignment from another OBJRECORD
            OBJRECORD& operator= (
               const OBJRECORD& rhs
               );

            //! Return the object description
            const MISTRING& GetDescription (
               ) const {
               return (m_desc);
               }

            //! Return the key field value for the FILE record related to this object
            INT32 GetFileID (
               ) const {
               return (m_FileID);
               }

            //! Return the full object name for this object.  This is a full name which
            //! may contain a path if the object is under a folder in the RVC file.
            const MISTRING& GetFullName (
               ) const {
               return (m_FullName);
               }

            //! Return the key field value for this object
            INT32 GetID (
               ) const {
               return (m_ID);
               }

            //! Return the object name for this object.
            const MISTRING& GetName (
               ) const {
               return (m_name);
               }

            //! Return the OBJTYPE of the object.
            INT32 GetObjType (
               ) const {
               return (m_otype);
               }

            //! Get bounding region for object.
            const REGION2D& GetRegion (
               ) const { return (m_Region); }

            //! Set the object description.
            void SetDescription (
               const UNICODE* desc
               ) { m_desc = desc; }

            //! Set the object description.
            void SetDescription (
               const MISTRING& desc
               ) { m_desc = desc; }

            //! Set the object's file ID.
            //! Warning:  The FILERECORD passed in MUST have been written 
            //! since writing the record gives it its unique ID.
            void SetFile (
               const FILERECORD& file
               ) { m_FileID = file.GetFileID(); }

            //! Set the full object name.
            //! The full name is the name plus object type tags and possibly
            //! folder path as returned from MfGetObjectName().
            void SetFullName (
               const UNICODE* name
               ) {
               m_FullName = name;
               return;
               }

            //! Set the full object name.
            //! The full name is the name plus object type tags and possibly
            //! folder path as returned from MfGetObjectName().
            void SetFullName (
               const MISTRING& name
               ) {
               m_FullName = name;
               return;
               }

            //! Set the object name (name only).
            void SetName (
               const UNICODE* name
               ) {
               m_name = name;
               return;
               }

            //! Set the object name (name only).
            void SetName (
               const MISTRING& name
               ) {
               m_name = name;
               return;
               }

            //! Set the object description
            //! (May not need this.  Use SetBasicInfo.)
            void SetObjectType (
               INT32 otype    //!< XXX Should become an enum when possible
               ) {
               m_otype = otype;
               return;
               }

         private:
            #ifndef GENERATING_DOXYGEN_OUTPUT

            void SetID (
               UINT32 id
               ) {
               m_ID = id;
               return;
               }
               
            UINT32 m_FileID;  
            UINT32 m_ID;      
            MISTRING m_name;
            MISTRING m_FullName;    //!< Full object name
            MISTRING m_desc;
            int m_otype;
            REGION2D m_Region;

            friend class GEOCAT;
            #endif // GENERATING_DOXYGEN_OUTPUT
         };

      //! Iterator for searching the catalog.
      class CONST_ITERATOR {
         public:
            //! Default constructor
            explicit CONST_ITERATOR (
               const GEOCAT *cat = 0
               ):
               m_cat(cat),
               m_Cursor(0),
               m_bIsEnd(true)
               { }

            //! Destructor
            ~CONST_ITERATOR (
               );

            //! Copy constructor
            CONST_ITERATOR (
               const CONST_ITERATOR& rhs
               );
         
            //! Assignment from CONST_ITERATOR
            CONST_ITERATOR& operator= (
               const CONST_ITERATOR& rhs
               );

            //! Dereference operator.  Returns reference to item
            const OBJRECORD& operator* (
               ) const {
               return (m_objrec);
               }

            //! Dereference operator.  Returns pointer to item
            const OBJRECORD* operator-> (
               ) const {
               return (&m_objrec);
               }

            //! Pre-increment operator.
            CONST_ITERATOR& operator++ (
               );

            //! Equality operator
            bool operator== (
               const CONST_ITERATOR& rhs
               ) const {
               return (m_cat == rhs.m_cat && (m_bIsEnd == rhs.m_bIsEnd || m_objrec.GetID() == rhs.m_objrec.GetID()));
               }
               
            //! Inequality operator
            bool operator!= (
               const CONST_ITERATOR& rhs
               ) const {
               return (!operator==(rhs));
               }

            //! Get "object" associated with current record.
            ERRVALUE GetObject (
               RVCOBJITEM& objitem,
               bool findnow = false
               ) const;

            //! Show progress within catalog.
            //! Also checks for "cancel" if enabled in status dialog/form.
            ERRVALUE ShowProgress (
               STATUSCONTEXT& scontext,            //!< Status context
               int line = 0                        //!< Line in progress dialog
               );
               
         private:
            #ifndef GENERATING_DOXYGEN_OUTPUT

            const GEOCAT* m_cat;
            GEOCAT_ITERATOR_CURSOR *m_Cursor;
            OBJRECORD m_objrec;
            bool m_bIsEnd;    //!< Set when we hit the end

            friend class GEOCAT;
            #endif // GENERATING_DOXYGEN_OUTPUT
         };

      // XXX If need non-const ITERATOR insert it here...

      //! Get CRS for objects used in catalogs.
      static const SPATREF::COORDREFSYS& GetCoordRefSys (
         );
      
      //! Default Constructor.
      //! Doesn't open anything.  Use Open or Make methods below.
      GEOCAT (
         );

      //! Destructor
      ~GEOCAT (
         );

      //! Return iterator pointing to first item in the catalog.
      CONST_ITERATOR Begin (
         ) const;

      //! Close the catalog
      ERRVALUE Close (
         );

      //! Returns an iterator which points one past the end.
      const CONST_ITERATOR& End (
         ) const {
         return (m_EndIterator);
         }

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

      //! Retrieve the record for a given file given it's ID.
      //! Returns -1 if record not found.
      ERRVALUE GetFileRecord (
         UINT32 id,
         FILERECORD& FileRecord
         ) const;

      //! Retrieve the FILERECORD for a given OBJECTRECORD.
      //! Returns -1 if record not found.
      ERRVALUE GetFileRecord (
         const OBJRECORD& ObjRecord,      //!< Object to get File Record for
         FILERECORD& FileRecord
         ) const {
         return (GetFileRecord(ObjRecord.GetFileID(), FileRecord));
         }

      //! Retrieve the record for a given file given a filepath pointing to the file.
      //! Returns -1 if not found.
      ERRVALUE GetFileRecord (
         const FILEPATH& filepath,
         FILERECORD& record
         ) const;

      //! Retrieve the record for a given object given it's ID.
      //! Returns -1 if record not found.
      ERRVALUE GetObjRecord (
         UINT32 id,
         OBJRECORD& record
         ) const;

      //! Create a catalog file.
      ERRVALUE Make (
         const FILEPATH& catalog
         );

      //! Open a catalog file.
      //! Catalog files have the extention ".gsc" for GeoSpatial Catalog
      //! May skip open mode parameter.  Just open for read and the scan
      //! methods can change it to write as needed.
      ERRVALUE Open (
         const FILEPATH& catalog,
         bool bCreateIfNotFound = false
         );
      
      //! Does a prescan of the directory counting files to index
      ERRVALUE PrescanDirectory (
         const FILEPATH& dir,
         STATUSCONTEXT& StatusContext,
         bool bScanSubDirs = true
         ) const;

      //! Remove all references to given file from the catalog.
      //! If the file is really a directory, it will remove references
      //! to all files in the given directory.
      ERRVALUE Remove (
         const FILEPATH& file
         );

      //! Remove all references to given file from the catalog.
      ERRVALUE Remove (
         const FILERECORD& record
         );

      //! Remove the record for a given object.
      ERRVALUE Remove (
         const OBJRECORD& record
         );

      //! Scan all RVC files in a given directory.
      //! Also scans the catalog for any files which were in this
      //! directory but are not there any more and deletes them from
      //! the catalog.
      //! If you want to provide status, call PrescanDirectory() to
      //! initialize the StatusContext
      ERRVALUE ScanDirectory (
         const FILEPATH& dir,
         STATUSCONTEXT* StatusContext = 0,
         bool bScanSubDirs = true
         );

      //! Scans an RVC file and adds or updates it's records in the catalog.
      //! If already cataloged and time stamp agrees, it won't do anyting.
      ERRVALUE ScanFile (
         const FILEPATH& file
         );

      //! Write an object record.
      //! If a record for the given object's ID already exists, it is updated.
      //! If the record does not exist, a new record is created, and the record's
      //! ID is updated.
      ERRVALUE Write (
         OBJRECORD& record
         );
      
      //! Write a file record. 
      //! If a record for the given file's ID already exists, it's timestamp is updated.
      //! If the record does not exist, a new record is created, and the record's
      //! ID is updated.
      ERRVALUE Write (
         FILERECORD& record
         );
      
   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

      ERRVALUE Read (
         int RecNum,
         FILERECORD& record
         ) const;

      ERRVALUE Read (
         int RecNum,
         OBJRECORD& record
         ) const;

      ERRVALUE Read (
         GEOCAT_ITERATOR_CURSOR* cursor,
         OBJRECORD& record
         ) const;

      ERRVALUE ReadObjRecord (
         INT32 recnum,
         UINT32 recnumtype,
         OBJRECORD& record
         ) const;

      ERRVALUE ScanFolder (
         int fhandle,
         RVCINODENUM parentinode,
         const FILERECORD& FileRecords
         );

      ERRVALUE ScanObject (
         int fhandle,
         RVCINODENUM objinode,
         int objtype,
         const FILERECORD& FileRecords
         );

      RVCFILEHANDLE m_fhandle;               //!< RVC file handle
      int m_dbhandle;                        //!< Database object handle
      int m_OpenCount;
      int m_FileTableNum;
      int m_ObjTableNum;
      int m_RgnTableNum;
      UINT8* m_recbuf;
      INT32 m_BufSize;
      FILEPATH m_filepath;
      CONST_ITERATOR m_EndIterator;          //!< So we can inline the End() method for much greater efficiency

      SIMPLE_ARRAY<DBFIELDINFO> m_FileFields;
      SIMPLE_ARRAY<DBFIELDINFO> m_ObjFields;
      SIMPLE_ARRAY<DBFIELDINFO> m_RgnFields;

      // UNIMPLEMENTED / UNSUPPORTED
      GEOCAT (const GEOCAT&);
      GEOCAT& operator= (const GEOCAT&);

      //! Iterator gets access to private Read() method.
      friend class CONST_ITERATOR;
      #endif // GENERATING_DOXYGEN_OUTPUT
   };


#endif

---