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

CATStream.h

Go to the documentation of this file.
00001 /// \file CATStream.h
00002 /// \brief Base stream interface
00003 /// \ingroup CAT
00004 ///
00005 /// Copyright (c) 2003-2007 by Michael Ellison.
00006 /// See COPYING.txt for the \ref gaslicense License (MIT License).
00007 ///
00008 // $Author: mikeellison $
00009 // $Date: 2008-01-21 08:33:12 -0600 (Mon, 21 Jan 2008) $
00010 // $Revision:   $
00011 // $NoKeywords: $
00012 
00013 
00014 #ifndef _CATStream_H_
00015 #define _CATStream_H_
00016 
00017 #include "CATInternal.h"
00018 #include "CATString.h"
00019 
00020 const int kCAT_DEFAULT_STREAM_BUF_SIZE = 4096;
00021 
00022 /// \class CATStream CATStream.h
00023 /// \brief Base interface for streams
00024 /// \ingroup CAT
00025 ///
00026 /// CATStream provides a generic stream interface class to be
00027 /// inherited by files, encrypted files, memory streams, and anything
00028 /// else that just needs basic read/write stream operations.
00029 ///
00030 /// \todo
00031 /// Need to add test cases to CATTests for all stream classes. They were converted
00032 /// from my old personal library, and haven't really been tested since conversion.
00033 class CATStream
00034 {
00035     /// CATSUBSTREAMBUILDER defines a factory function that child classes can use to
00036     /// create substreams of a requested type.  Each stream type should have a
00037     /// CATStreamXXXX_Builder() function of this type. Pass it into the
00038     /// CreateSubStream() function to build a substream of that type.
00039     ///
00040     /// The meaning of the parameters depends upon the type of substream.
00041     typedef CATStream* (*CATSUBSTREAMBUILDER)(CATInt64      offset, 
00042                                               CATInt64      length, 
00043                                               CATStream*    parent, 
00044                                               void*         param1, 
00045                                               CATUInt32     param2);
00046    public:         
00047          /// File open modes.
00048          ///
00049          /// More are possible, but I'd like to only add as we need them
00050          /// beyond the basics. If you add any, ensure that conflicts
00051          /// aren't created between sections.
00052          ///
00053          /// You can combine flags from different sections,
00054          /// but don't mix flags within a section.
00055          ///
00056          /// Binary mode is assumed. Currently no support for text mode
00057          /// is provided. Text mode is fugly - specify your carriage returns
00058          /// accordingly.
00059          ///   
00060          /// Default mode is read only / existing only / shareable.
00061          enum OPEN_MODE
00062          {
00063             //-------------------------
00064             // Read / write / create
00065             READ_ONLY                 = 0x0,
00066             READ_WRITE_EXISTING_ONLY  = 0x1,
00067             READ_WRITE_EXISTING_FIRST = 0x2,
00068             READ_WRITE_CREATE_TRUNC   = 0x3,
00069             WRITE_CREATE_ONLY         = 0x4,
00070             //-------------------------
00071             // Share flags
00072             //-------------------------
00073             SHARE_ALL            = 0x0,
00074             SHARE_NONE           = 0x100
00075          };
00076 
00077          CATStream()
00078          {
00079             fSubCount = 0;
00080          }
00081 
00082          virtual ~CATStream()
00083          {            
00084             CATASSERT(fSubCount == 0, "SubStreams are still active.");
00085          }
00086 
00087          /// Open() opens a stream from a pathname.
00088          ///
00089          /// Call close when done.
00090          ///
00091          /// \param pathname - Ptr to path string.  Platform-specific
00092          ///        issues should be taken care of by child classes if needed.
00093          /// \param mode - combination of OPEN_MODE enumerated flags.
00094          ///
00095          /// \return CATResult - CAT_SUCCESS on success.
00096          /// \sa Close()
00097          virtual CATResult Open(const CATWChar* pathname, OPEN_MODE mode)   = 0;
00098          
00099          /// Close() closes a previously opened stream.
00100          /// 
00101          /// Stream must have been previously successfuly opened.
00102          ///
00103          /// \return CATResult - CAT_SUCCESS on success.
00104          /// \sa Open()
00105          virtual CATResult Close() = 0;
00106 
00107          /// IsOpen() returns true if the stream has been opened, and false otherwise.
00108          ///
00109          /// \return bool - true if stream is open.
00110          /// \sa Open(), Close()
00111          virtual bool     IsOpen() = 0;
00112 
00113          /// Read() reads the requested amount of data into a buffer.
00114          ///
00115          /// Will read up to, but not necessarily, [length] bytes.
00116          /// On return, length is set to the number of bytes actually read.
00117          /// buffer *must* be large enough for max value of length.
00118          /// 
00119          /// \param buffer - target buffer for read
00120          /// \param length - min(length of buffer, desired read length).
00121          ///        Set to amount read on return.
00122          /// \return CATResult - CAT_SUCCESS on success
00123          /// \sa Write()
00124          virtual CATResult Read(void* buffer, CATUInt32& length) = 0;
00125 
00126          /// Write() writes the requested amount of data from a buffer.
00127          ///
00128          /// Incomplete writes are treated as an error.
00129          /// 
00130          /// \param buffer - source buffer to write from.
00131          /// \param length - length of data to write.
00132          /// \return CATResult - CAT_SUCCESS on success
00133          /// \sa Read()
00134          virtual CATResult Write(const void* buffer, CATUInt32 length) = 0;
00135          
00136          /// ReadAbs() reads from the specified location, but does
00137          /// not change the current stream position.
00138          ///
00139          /// ReadAbs() is mainly for use in substreams, and may not be
00140          /// available from all stream types.  If you're not implementing
00141          /// it, then please return an error from your derived class.
00142          ///
00143          /// \param buffer - target buffer for read
00144          /// \param length - min(length of buffer, desired read length).
00145          ///                 set to amount read on return.
00146          /// \param position - position within stream to read.
00147          ///  \return CATResult - CAT_SUCCESS on success.
00148          virtual CATResult ReadAbs(void *buffer, CATUInt32& length, CATInt64 position) = 0;
00149 
00150          /// WriteAbs() Writes from the specified location, but does
00151          /// not change the current stream position.
00152          ///
00153          /// WriteAbs() is mainly for use in substreams, and may not be
00154          /// available from all stream types.  If you're not implementing
00155          /// it, then please return an error from your derived class.
00156          ///
00157          /// \param buffer - target buffer for Write
00158          /// \param length - length of data to write        
00159          /// \param position - position within stream to read.
00160          ///  \return CATResult - CAT_SUCCESS on success.
00161          virtual CATResult WriteAbs(const void *buffer, CATUInt32 length, CATInt64 position) = 0;
00162 
00163          /// CreateSubStream() creates a substream that uses this stream for I/O at
00164          /// a specified offset and length.  
00165          ///
00166          /// You must call ReleaseSubStream()  when you are done with the substream.
00167          ///
00168          /// \param streamOffset - offset within the stream that should be the start of the
00169          ///                       substream. This is an absolute position, and is not
00170          ///                       related to the stream's current position.         
00171          ///
00172          /// \param streamLength - length of the substream. If set to -1, it will 
00173          ///                       use the entire length of the parent stream.
00174          /// \param  builder - substream builder for specialized substream types
00175          /// \param  param1 - void*, meaning depends on substream type
00176          /// \param param2 - CATUInt32, meaning depends on substream type
00177          /// \return CATStream* - ptr to new stream or null on failure
00178          /// \sa ReleaseSubStream()
00179          virtual CATStream* CreateSubStream(  CATInt64            streamOffset, 
00180                                               CATInt64            streamLength,                                           
00181                                               CATSUBSTREAMBUILDER builder = CATStream::DefSubStreamBuilder,
00182                                               void*               param1  = 0,
00183                                               CATUInt32           param2  = 0);
00184 
00185          /// ReleaseSubStream() releases a previously allocated substream.         
00186          ///
00187          /// \param subStream - ref to sub stream. Set to 0 on successful release.
00188          /// \return CATResult - CAT_SUCCESS on success.
00189          virtual CATResult ReleaseSubStream( CATStream*& subStream );
00190 
00191 
00192          /// Size() returns the size of the object in filesize.
00193          ///
00194          /// This may not be supported on all stream types.
00195          /// \param filesize - 64-bit length of stream.
00196          /// \return CATResult - CAT_SUCCESS on success
00197          virtual CATResult Size(CATInt64& filesize) = 0;
00198 
00199          /// IsSeekable() returns true if the stream is a seekable type.
00200          ///
00201          /// Some streams might not be seekable - check before seeking.
00202          ///
00203          /// \return bool - true if stream is seekable.
00204          /// \sa SeekRelative(), SeekAbsolute(), SeekFromEnd()
00205          virtual bool     IsSeekable() = 0;
00206          
00207          /// SeekRelative() seeks from current position to a
00208          /// relative location.
00209          ///
00210          /// Some streams might not be seekable - see IsSeekable().
00211          ///
00212          /// \param offset - signed offset from current position
00213          /// \return CATResult - CAT_SUCCESS on success.
00214          /// \sa IsSeekable(), SeekAbsolute(), SeekFromEnd()
00215          virtual CATResult SeekRelative(CATInt32  offset) = 0;
00216 
00217 
00218          /// SeekAbsolute() seeks from the start of the stream
00219          /// to an absolute position.
00220          ///
00221          /// Some streams might not be seekable - see IsSeekable().
00222          ///
00223          /// \param position - unsigned absolute position to seek to.
00224          /// \return CATResult - CAT_SUCCESS on success.
00225          /// \sa IsSeekable(), SeekRelative(), SeekFromEnd()
00226          virtual CATResult SeekAbsolute(CATInt64 position) = 0;
00227 
00228          /// SeekFromEnd() seeks from the end of the stream.
00229          ///
00230          /// For example, an offset of 5 will be 5 bytes before
00231          /// the end of the stream.
00232          ///
00233          /// Some streams might not be seekable - see IsSeekable()
00234          ///
00235          /// \param offset - signed offset from end of stream
00236          /// \return CATResult - CAT_SUCCESS on success.
00237          /// \sa IsSeekable(), SeekRelative(), SeekAbsolute()
00238          virtual CATResult SeekFromEnd(CATInt32 offset) = 0;        
00239          
00240          /// GetPosition() returns the current position in the stream
00241          /// in position.
00242          ///
00243          /// Stream must be seekable to know the position.
00244          ///
00245          /// \param position - current position - set on successful return.
00246          /// \return CATResult - CAT_SUCCESS on success.
00247          /// \sa IsSeekable(), Size()
00248          virtual CATResult GetPosition(CATInt64& position) = 0;
00249 
00250 
00251          /// GetName() retrieves the name of the stream.
00252          ///
00253          /// Typically, this is a path or filename type name.
00254          ///
00255          virtual CATString GetName() const = 0;
00256 
00257          /// Copy from one stream to another using the specified buffer size
00258          virtual CATResult CopyToStream( CATStream*  outputStream, 
00259                                          CATUInt32   bufSize     = kCAT_DEFAULT_STREAM_BUF_SIZE, 
00260                                          CATInt64    offset      = 0, 
00261                                          CATInt64    length      = 0);
00262 
00263          /// This is the default substream builder - it creates just CATStreamSub*'s.
00264          static CATStream* DefSubStreamBuilder( CATInt64   offset, 
00265                                                 CATInt64   length, 
00266                                                 CATStream* parent, 
00267                                                 void*      param1, 
00268                                                 CATUInt32  param2);
00269    protected:
00270       CATUInt32  fSubCount;   
00271 
00272    private:
00273       CATStream& operator=(const CATStream& stream)
00274       {
00275          CATASSERT(false,"Copying not currently supported.");
00276       }
00277 
00278       
00279 };
00280 
00281 
00282 #endif // _CATStream_H_

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