BinaryStream Class Reference
 
 
 
BinaryStream Class Reference

#include <maxbinarystream.h>

Inheritance diagram for BinaryStream:
MaxHeapOperators BinaryStreamMemory

Class Description

Represent an abstract binary stream of data.

Public Types

typedef __int64  OffsetType

Public Member Functions

  BinaryStream ()
  Default Constructor.
virtual  ~BinaryStream ()
  Destructor.
virtual MaxString  LastError () const =0
  Returns the last error encountered using the stream.
virtual bool  IsEndOfFile () const =0
  Returns true when at end of file.
virtual bool  CanWrite () const =0
  Returns true if a call to Write(void*, size_t) would succeed.
virtual size_t  Read (void *data, size_t length)=0
  Read a specified number bytes from this stream and stores it in the data parameter.
virtual size_t  Write (const void *data, size_t length)=0
  Write a number of bytes from the data parameter to this stream.
virtual OffsetType  Seek (OffsetType offset, int direction)=0
  Move the pointer inside this stream to a specified position.
virtual void  Flush ()=0
  Make sure that all the buffer are synced with the OS native objects.
virtual void  Truncate ()=0
  Erase all the data after the current position.

Static Public Member Functions

static unsigned int  ParseStreamMode (const MCHAR *streamMode=_M("rt"))
  Transform a C fopen-style file mode into a file mode that you can use in the BinaryStream::FromFilename parameter.
static BinaryStream FromFilename (const MaxString &fileName, unsigned int mode, MaxString *error=NULL)
  Create an abstract BinaryStream that will point to the specified file.
static BinaryStream FromFilename (const MaxString &fileName, bool write=false, bool truncate=false, bool exclusive=false, MaxString *error=NULL)
  Create an abstract BinaryStream that will point to the specified file.
static BinaryStream FromFileHandle (HANDLE handle, bool closeOnDelete=true)
  Create an abstract BinaryStream out of a Win32 file handle.
static BinaryStream FromFile (FILE *file, bool closeOnDelete=true)
  Create an abstract BinaryStream out of a Win32 file handle.
static BinaryStreamMemory FromMemory (void *data, size_t length, void(*freeFunction)(void *))
  Create an abstract BinaryStream pointing to a memory region.
static BinaryStreamMemory FromMemory (void *data, size_t length, void *(*reallocFunction)(void *, size_t), void(*freeFunction)(void *))
  Create an abstract BinaryStream pointing to a memory region.

Member Typedef Documentation


Constructor & Destructor Documentation

BinaryStream ( ) [inline]

Default Constructor.

{}
virtual ~BinaryStream ( ) [inline, virtual]

Destructor.

{}

Member Function Documentation

virtual MaxString LastError ( ) const [pure virtual]

Returns the last error encountered using the stream.

If no error occurred during the uses of this class, this function will returns null. If for any reason, any call to this interface, this member will returns a user-readable error code that explain why the operation failed.

Implemented in BinaryStreamMemory.

virtual bool IsEndOfFile ( ) const [pure virtual]

Returns true when at end of file.

Implemented in BinaryStreamMemory.

virtual bool CanWrite ( ) const [pure virtual]

Returns true if a call to Write(void*, size_t) would succeed.

Implemented in BinaryStreamMemory.

virtual size_t Read ( void *  data,
size_t  length 
) [pure virtual]

Read a specified number bytes from this stream and stores it in the data parameter.

Parameters:
[out] data - Buffer to store the bytes taken out of this stream.
length - Number of bytes available in "data" to store the content of this stream.
Returns:
Returns the number of bytes read. Or 0 if the end of file was reached.

Implemented in BinaryStreamMemory.

virtual size_t Write ( const void *  data,
size_t  length 
) [pure virtual]

Write a number of bytes from the data parameter to this stream.

Parameters:
[in] data - The byte source to copy from
length - The number of bytes to copy from the data parameter.
Returns:
Returns the number of bytes written.

Implemented in BinaryStreamMemory.

virtual OffsetType Seek ( OffsetType  offset,
int  direction 
) [pure virtual]

Move the pointer inside this stream to a specified position.

Parameters:
offset - The amount to offset the file pointer by.
direction - Can be either SEEK_SET, SEEK_CUR, SEEK_END.

Implemented in BinaryStreamMemory.

virtual void Flush ( ) [pure virtual]

Make sure that all the buffer are synced with the OS native objects.

Implemented in BinaryStreamMemory.

virtual void Truncate ( ) [pure virtual]

Erase all the data after the current position.

Implemented in BinaryStreamMemory.

static unsigned int ParseStreamMode ( const MCHAR *  streamMode = _M("rt") ) [static]

Transform a C fopen-style file mode into a file mode that you can use in the BinaryStream::FromFilename parameter.

Here is the table of interpretation. It was made to match Microsoft's VC Runtime interpretation:

r: BINARYSTREAM_MODE_READ r+ or rw: BINARYSTREAM_MODE_READ | BINARYSTREAM_MODE_WRITE w: BINARYSTREAM_MODE_WRITE | BINARYSTREAM_MODE_CREATE | BINARYSTREAM_MODE_TRUNCATE w+: BINARYSTREAM_MODE_READ | BINARYSTREAM_MODE_WRITE | BINARYSTREAM_MODE_CREATE | BINARYSTREAM_MODE_TRUNCATE a: BINARYSTREAM_MODE_WRITE | BINARYSTREAM_MODE_APPEND | BINARYSTREAM_MODE_CREATE a+: BINARYSTREAM_MODE_READ | BINARYSTREAM_MODE_WRITE | BINARYSTREAM_MODE_APPEND | BINARYSTREAM_MODE_CREATE

And you can add the following suffix: b: BINARYSTREAM_MODE_BINARY t: BINARYSTREAM_MODE_TEXT e: BINARYSTREAM_MODE_EXCLUSIVE

If the stream mode contains any invalid sequence or unknown character, it will returns 0.

static BinaryStream* FromFilename ( const MaxString fileName,
unsigned int  mode,
MaxString error = NULL 
) [static]

Create an abstract BinaryStream that will point to the specified file.

Parameters:
fileName The file's name you wish to open.
mode Specify how to open the file.
error If this parameter is not null, it will contains an error string if this function fails.
static BinaryStream* FromFilename ( const MaxString fileName,
bool  write = false,
bool  truncate = false,
bool  exclusive = false,
MaxString error = NULL 
) [static]

Create an abstract BinaryStream that will point to the specified file.

Parameters:
fileName The file's name you wish to open.
write Open for write ?
truncate Will erase the file prior to open it.
exclusive Prevent any other object or process to open it simultaneously.
error If this parameter is not null, it will contains an error string if this function fails.
static BinaryStream* FromFileHandle ( HANDLE  handle,
bool  closeOnDelete = true 
) [static]

Create an abstract BinaryStream out of a Win32 file handle.

Parameters:
handle - The file handle.
closeOnDelete - Will call CloseHandle(HANDLE) when the new object will be destroyed.
static BinaryStream* FromFile ( FILE *  file,
bool  closeOnDelete = true 
) [static]

Create an abstract BinaryStream out of a Win32 file handle.

Parameters:
file - The file pointer.
closeOnDelete - Will call fclose(FILE*) when the new object will be destroyed.
static BinaryStreamMemory* FromMemory ( void *  data,
size_t  length,
void(*)(void *)  freeFunction 
) [static]

Create an abstract BinaryStream pointing to a memory region.

Parameters:
data - Initial data.
length - Initial data's length. (Can be 0.)
freeFunction - Function to call when this object is destroyed. (Can be NULL.)
static BinaryStreamMemory* FromMemory ( void *  data,
size_t  length,
void *(*)(void *, size_t)  reallocFunction,
void(*)(void *)  freeFunction 
) [static]

Create an abstract BinaryStream pointing to a memory region.

Parameters:
data - Initial data.
length - Initial data's length. (Can be 0.)
reallocFunction - Function to call when data needs to be resized. (Can be NULL.)
freeFunction - Function to call when this object is destroyed. (Can be NULL.)