Game Accessibility Library logo SourceForge.net Logo
Game Accessibility Suite: CAT/CATStreamRAM.h Source File

CATStreamRAM.h

Go to the documentation of this file.
00001 //---------------------------------------------------------------------------
00002 /// \file CATStreamRAM.h
00003 /// \brief RAM stream
00004 /// \ingroup CAT
00005 ///
00006 /// Copyright (c) 2003-2007 by Michael Ellison.
00007 /// See COPYING.txt for the \ref gaslicense License (MIT License).
00008 ///
00009 // $Author: mikeellison $
00010 // $Date: 2008-01-21 08:33:12 -0600 (Mon, 21 Jan 2008) $
00011 // $Revision:   $
00012 // $NoKeywords: $
00013 //
00014 //---------------------------------------------------------------------------
00015 #ifndef CATStreamRAM_H_
00016 #define CATStreamRAM_H_
00017 
00018 #include "CATStream.h"
00019 
00020 /// \class CATStreamRAM
00021 /// \brief Memory-based stream class - acts as a file in RAM
00022 /// \ingroup CAT
00023 class CATStreamRAM : public CATStream
00024 {
00025    public:
00026          /// Default constructor doesn't do much - you'll need
00027          /// to call Open() before trying to do much.
00028          CATStreamRAM();
00029 
00030          /// Destructor will close file handle if its unclosed, but
00031          /// will assert in debug mode if you do this.
00032          ///
00033          /// Please call Close() before destroying a file if you
00034          /// have opened it previously.
00035          /// \sa Close()
00036          virtual ~CATStreamRAM();
00037 
00038          /// Open() opens a file from a pathname.
00039          ///
00040          /// Call close when done.
00041          ///
00042          /// \param name - not really critical, but you're welcome to name ram files.
00043          /// \param mode - currently ignored.
00044          ///
00045          /// \return CATResult - CAT_SUCCESS on success.
00046          /// \sa Close()
00047          virtual CATResult Open(const CATWChar* name, OPEN_MODE mode);
00048          
00049          /// Close() closes a previously opened file.
00050          /// 
00051          /// File must have been previously successfuly opened.
00052          ///
00053          /// \return CATResult - CAT_SUCCESS on success.
00054          /// \sa Open()
00055          virtual CATResult Close();
00056 
00057          /// IsOpen() returns true if the file has been opened, and false otherwise.
00058          ///
00059          /// \return bool - true if file is open.
00060          /// \sa Open(), Close()
00061          virtual bool IsOpen();
00062 
00063          /// Read() reads the requested amount of data into a buffer.
00064          ///
00065          /// Will read up to, but not necessarily, [length] bytes.
00066          /// On return, length is set to the number of bytes actually read.
00067          /// buffer *must* be large enough for max value of length.
00068          /// 
00069          /// \param buffer - target buffer for read
00070          /// \param length - min(length of buffer, desired read length).
00071          ///        Set to amount read on return.
00072          /// \return CATResult - CAT_SUCCESS on success
00073          /// \sa Write()
00074          virtual CATResult Read(void* buffer, CATUInt32& length);
00075 
00076          /// Write() writes the requested amount of data from a buffer.
00077          ///
00078          /// Incomplete writes are treated as an error.
00079          /// 
00080          /// \param buffer - source buffer to write from.
00081          /// \param length - length of data to write.
00082          /// \return CATResult - CAT_SUCCESS on success
00083          /// \sa Read()
00084          virtual CATResult Write(const void* buffer, CATUInt32 length);
00085          
00086          /// Size() returns the size of the object in filesize.
00087          ///
00088          /// This may not be supported on all stream types.
00089          /// \param filesize - 64-bit length of file.
00090          /// \return CATResult - CAT_SUCCESS on success
00091          virtual CATResult Size(CATInt64& filesize);
00092 
00093          /// IsSeekable() returns true for files.
00094          virtual bool     IsSeekable();
00095          
00096          /// SeekRelative() seeks from current position to a
00097          /// relative location.
00098          ///
00099          /// \param offset - signed offset from current position
00100          /// \return CATResult - CAT_SUCCESS on success.
00101          /// \sa IsSeekable(), SeekAbsolute(), SeekFromEnd()
00102          virtual CATResult SeekRelative(CATInt32  offset);
00103 
00104 
00105          /// SeekAbsolute() seeks from the start of the file
00106          /// to an absolute position.
00107          ///
00108          /// \param position - unsigned absolute position to seek to.
00109          /// \return CATResult - CAT_SUCCESS on success.
00110          /// \sa IsSeekable(), SeekRelative(), SeekFromEnd()
00111          virtual CATResult SeekAbsolute(CATInt64 position);
00112 
00113          /// SeekFromEnd() seeks from the end of the file.
00114          ///
00115          /// \param offset - signed offset from end of stream
00116          /// \return CATResult - CAT_SUCCESS on success.
00117          /// \sa IsSeekable(), SeekRelative(), SeekAbsolute()
00118          virtual CATResult SeekFromEnd(CATInt32 offset);
00119          
00120          /// GetPosition() returns the current position in the stream
00121          /// in position.
00122          ///
00123          /// \param position - current position - set on successful return.
00124          /// \return CATResult - CAT_SUCCESS on success.
00125          /// \sa IsSeekable(), Size()
00126          virtual CATResult GetPosition(CATInt64& position);
00127 
00128          /// GetName() retrieves the filename of the stream.
00129          virtual CATString GetName() const;
00130 
00131          /// ReadAbs() reads from the specified location, but does
00132          /// not change the current stream position.
00133          ///
00134          /// ReadAbs() is mainly for use in substreams, and may not be
00135          /// available from all stream types.  If you're not implementing
00136          /// it, then please return an error from your derived class.
00137          ///
00138          /// \param buffer - target buffer for read
00139          /// \param length - min(length of buffer, desired read length).
00140          ///                 set to amount read on return.
00141          /// \param position - position within stream to read.
00142          ///  \return CATRESULT - CAT_SUCCESS on success.
00143          virtual CATResult ReadAbs(void *buffer, CATUInt32& length, CATInt64 position);
00144 
00145          /// WriteAbs() Writes from the specified location, but does
00146          /// not change the current stream position.
00147          ///
00148          /// WriteAbs() is mainly for use in substreams, and may not be
00149          /// available from all stream types.  If you're not implementing
00150          /// it, then please return an error from your derived class.
00151          ///
00152          /// \param buffer - target buffer for Write
00153          /// \param length - length of data to write        
00154          /// \param position - position within stream to read.
00155          ///  \return CATRESULT - CAT_SUCCESS on success.
00156          virtual CATResult WriteAbs(const void *buffer, CATUInt32 length, CATInt64 position);
00157 
00158          /// ReallocCache() reallocates the cache memory to at least
00159          /// as large as minLength.
00160          CATResult ReallocCache( CATInt32 minLength );
00161 
00162          /// ShrinkCache() shrinks the cache to exactly the current fSize().
00163          CATResult ShrinkCache();
00164 
00165          /// FromFile() loads a file into the RAM stream. This is analogous
00166          /// to calling Open() on a file stream, only your read/writes
00167          /// will be a hell of a lot faster.
00168          ///
00169          /// As in Open(), please close prior to opening a new one, and 
00170          /// close before destroying.
00171          ///
00172          /// \param pathName - path of file to open
00173          ///
00174          /// \return CATResult - CAT_SUCCESS on success.
00175          CATResult FromFile(const CATWChar* pathName);
00176 
00177          /// ToFile() saves the stream to a file.
00178          ///
00179          /// \param pathName - path of file to save
00180          /// \param overwrite - if false, will return an error if the file already exists.
00181          ///
00182          /// \return CATResult - CAT_SUCCESS on success.
00183          CATResult ToFile(const CATWChar* pathName, bool overwrite = true);
00184 
00185          /// GetRawCache() retrieves a raw pointer to the buffer.
00186          /// WARNING: this pointer is only valid until another stream command
00187          /// is made.  Stream operations may change the cache pointer, causing
00188          /// use of the returned pointer to cause an access violation.
00189          /// \return CATUInt8* - temporary pointer to cache
00190          CATUInt8* GetRawCache();
00191 
00192 
00193          
00194    private:
00195          
00196          CATStreamRAM& operator=(const CATStreamRAM& srcStream)
00197          {
00198             CATASSERT(false,"Copy operator not currently supported for files.");
00199             return *this;
00200          }      
00201 
00202          CATUInt8*     fRamCache;
00203          CATInt32      fCacheSize;
00204          CATInt32      fSize;
00205          CATInt32      fCurPos;         
00206          CATString     fStreamName;         
00207 };
00208 
00209 #endif // CATStreamRAM_H_
00210 
00211 

Generated on Mon Feb 11 04:09:48 2008 for Game Accessibility Suite by doxygen 1.5.4