list.h

Go to the documentation of this file.

/**
 * \file rvc/list.h 
 * \brief interface for the RVC::LIST class.
 *
 * \if NODOC
 * $Id: list.h_v 1.9 2004/02/26 21:53:17 scowan Exp $
 *
 * $Log: list.h_v $
 * Revision 1.9  2004/02/26 21:53:17  scowan
 * Fixed compiler warning.
 *
 * Revision 1.8  2003/10/07 17:32:23  scowan
 * Object virtual method changes.
 *
 * Revision 1.7  2003/09/30 16:52:06  dwilliss
 * Doxygen
 *
 * Revision 1.6  2003/09/25 21:20:04  dwilliss
 * Fixed doxygen comment
 *
 * Revision 1.5  2003/09/15 13:49:45  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.4  2003/08/27 21:27:06  scowan
 * Uses new rvc list class interface and handle.
 *
 * Revision 1.3  2003/04/09 21:24:45  dwilliss
 * Don't use _T in templates.  Mac's ctype.h defines a global _T
 *
 * Revision 1.2  2001/06/14 19:09:50  scowan
 * Added to RVC namespace.
 *
 * Revision 1.1  2001/05/24 16:11:59  scowan
 * Initial revision
 *
 * \endif
**/

//!   \class RVC::LIST rvc/list.h
//!   \brief Manages RVC::OBJTYPE_GenericRef objects.  
//!   
//!   The interface currently wraps the MfList functions.
//!   
//!   RVC Object Types that this class supports: RVC::OBJTYPE_GenericRef.
//!
//!   Default RVC Object Type for this class: RVC::OBJTYPE_GenericRef.
//!
//!   Valid parents for this class:
//!      - RVC::OBJTYPE_File
//!      - RVC::OBJTYPE_Folder

#ifndef INC_RVC_LIST_H
#define INC_RVC_LIST_H

#ifndef INC_RVC_OBJECT_H
   #include <rvc/object.h>
#endif

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

#ifndef GENERATING_DOXYGEN_OUTPUT
struct RVCGENLISTINFO;     // Forward declarations
#endif // GENERATING_DOXYGEN_OUTPUT

namespace RVC {

#ifndef GENERATING_DOXYGEN_OUTPUT
class LISTHANDLE;    // Forward declarations
#endif // GENERATING_DOXYGEN_OUTPUT

class LIST : public RVC::OBJECT {
   public:

      //! Default constructor
      LIST (
         );

      //! Copy constructor
      LIST (
         const RVC::LIST& obj
         );

      //! Destructor
      virtual ~LIST (
         );

      //! Assignment.  Will close if necessary and reopen if 'rhs' is open
      RVC::LIST& operator= (
         const RVC::LIST& rhs
         );

      //! Obtain the size of a list entry
      //! @return List entry size   
      INT32 GetItemSize (
         INT32 ItemNum
         ) const;
         
      //! Obtain the size of the largest list entry
      //! @return Largest list entry size 
      INT32 GetMaxItemSize (
         ) const;
         
      //! Obtain the number of list entries
      //! @return Number of list entries
      INT32 GetNumItems (
         ) const;
      
      //! Inserts 1 or more entries into a generic list with each new entry initially the size of zero
      ERRVALUE InsertItems (
         INT32 StartPosn,
         INT32 NumItems = 1
         );

      //! Create a new rvc list object under a specified parent rvc object with name, description, and source
      ERRVALUE Make (
         const RVC::OBJECT& parent,       //!< Parent object to create list object under
         const RVC::OBJECTNAME& name,        //!< Name of new list object
         const RVC::OBJECTDESC& desc,        //!< Description of new list object
         const char* Source = 0           //!< Source of new list object, default is application name
         );

      //! Create a new rvc list object under a specified parent rvc object with name, description, and source
      ERRVALUE Make (
         const RVC::OBJITEM& ObjItem,
         const char* Source = 0           //!< Source of new list object, default is application name
         );

      //! Read a list entry
      //! @return Number of bytes of the entry     
      INT32 Read (
         INT32 ItemNum,
         void *ptr
         ) const;

      //! Read a list entry
      //! @return Number of bytes of the entry     
      INT32 Read (
         INT32 ItemNum,
         void **buffer,
         INT32 BufferSize
         ) const;

      //! Read a list entry into a SIMPLE_ARRAY
      template <class _CT>
      ERRVALUE Read (
         INT32 ItemNum,
         SIMPLE_ARRAY<_CT>& data
         ) const {
         INT32 MaxItems = data.GetMaxItems();
         _CT* buffer = data.Detach();
         INT32 NumBytes = Read(ItemNum, reinterpret_cast<void**>(&buffer), MaxItems * sizeof(_CT));
         if (NumBytes < 0) {
            data.Attach(buffer, MaxItems);
            data.Clear();
            }
         else {
            if (static_cast<UINT32>(NumBytes) > MaxItems * sizeof(_CT)) MaxItems = NumBytes / sizeof(_CT);
            data.Attach(buffer, MaxItems);
            data.Resize(NumBytes / sizeof(_CT), true, false);  //! Set to correct number of items
            NumBytes = 0;
            }
         return (NumBytes);
         }
         
      //! Partially read a list entry
      //! @return Number of bytes read of the entry      
      INT32 Read (
         INT32 ItemNum,
         INT32 StartPosn,
         INT32 Length,
         void *ptr
         ) const;

      //! Read a list entry into a SIMPLE_ARRAY
      template <class _CT>
      ERRVALUE Read (
         INT32 ItemNum,
         INT32 StartPosn,
         INT32 Length,        //!< Length in _CT units
         SIMPLE_ARRAY<_CT>& data
         ) const {
         INT32 NumBytes = ReadPartial(ItemNum, StartPosn * sizeof(_CT), Length * sizeof(_CT), static_cast<void*>(data));
         if (NumBytes >= 0) {
            data.Resize(NumBytes / sizeof(_CT), true, false);  //! Set to correct number of items
            NumBytes = 0;
            }
         return (NumBytes);
         }
         
      //! Resize the list to a new number of items
      ERRVALUE Resize (
         INT32 NewNumItems
         );

      //! Resize a list item to a new size      
      ERRVALUE ResizeItem (
         INT32 ItemNum,
         INT32 NewItemSize
         );
         
      //! Swap two list items
      ERRVALUE SwapItems (
         INT32 Item1,
         INT32 Item2
         );
         
      //! Write data to a list item
      //! @return Number of bytes written
      INT32 Write (
         INT32 ItemNum,
         INT32 Length,
         const void* ptr
         );
         
      //! Write partial data to a list item
      //! @return Number of bytes written
      INT32 Write (
         INT32 ItemNum,
         INT32 TotalSize,
         INT32 StartPosn,
         INT32 Length,
         const void* ptr
         );
         
      //! Write SIMPLE_ARRAY<> to a list item
      template <class _CT>
      ERRVALUE Write (
         INT32 ItemNum,
         const SIMPLE_ARRAY<_CT>& data
         ) {
         ERRVALUE err = Write(ItemNum, data.GetNumItems() * sizeof(_CT), data);
         if (err > 0) err = 0;
         return (err);
         }
         
   protected:     
      
      //! Used for objects that inherit from this object
      ERRVALUE Make (const OBJECT& parent, const OBJECTNAME& name, const OBJECTDESC& desc, RVCGENLISTINFO& newinfo, int HeaderSize, int HeaderType, const char* Source);

      //! Used for objects that inherit from this object
      ERRVALUE OpenObject (OPENMODE OpenFlags, RVCGENLISTINFO& newinfo, int HeaderSize, int HeaderType, MDLGPARENT parent);
      
   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

      //! Implementation of RVC::OBJECT virtual methods
      virtual ERRVALUE v_CloseObject ();           //! Close the open object
      virtual OBJTYPE v_GetDftObjectType () const;    //!< Get the default object type
      virtual bool v_IsObjectOpen () const;              //!< Is this object opened?
      virtual ERRVALUE v_OpenObject (OPENMODE OpenFlags, MDLGPARENT parent);           //! Open the object

      LISTHANDLE* m_ListHandle;
      #endif // GENERATING_DOXYGEN_OUTPUT
   };

}     //! End of RVC namespace

#endif   //!< INC_RVC_LIST_H

---