LStream is a PowerPlant class that is used for managing data streaming in PowerPlant. By abstracting low-level data sourcing and sinking away from objects, you can read and write data without regard to where it came from or is going to.
Methods :
The methods in this class are:
Data Members:
The data members in this class are:
Operation:
The PowerPlant Book contains a detailed description of how to work with this class. Refer there for more information.
Source files:
Purpose:
The constructor creates an object. There are two constructors for LStream. The first is the default constructor. The second is the copy constructor
Access :
Prototype:
LStream();
LStream::LStream( const LStream& inOriginal )Parameters:
Purpose:
The destructor destroys the LStream object.
Access :
Prototype:
virtual ~LStream();
Purpose:
This method tells if the end of the stream has been reached.
Access :
Prototype:
Boolean AtEnd() const;Parameters:
Return:
Returns true if at the end of the stream.
Purpose:
Read bytes from a Stream to a buffer. Subclasses must override this function to support reading.
Access :
Prototype:
ExceptionCode GetBytes(
void* outBuffer, SInt32& ioByteCount) Return:
Returns an error code and passes back the number of bytes actually read, which may be less than the number requested if an error occurred.
Remarks:
You should not throw an Exception out of this function.
Purpose:
Return the length, in bytes, of the Stream
Access :
Prototype:
SInt32 GetLength() const;Parameters:
Return:
Purpose:
Return the Read/Write Marker position
Access :
Prototype:
SInt32 GetMarker() const;Parameters:
Return:
Remarks:
Position is a byte offset from the start of the Stream.
Purpose:
Read data from a Stream to a buffer, without moving the Marker
Access :
Prototype:
SInt32 PeekData(
void* outBuffer, SInt32 inByteCount) Return:
The number of bytes actually read, which may be less than the number requested if an error occurred.
Purpose:
Write bytes from a buffer to a Stream
Subclasses must override this function to support writing.
Access :
Prototype:
ExceptionCode PutBytes(
const void* inBuffer, SInt32 &ioByteCount) Return:
Returns an error code and passes back the number of bytes actually written, which may be less than the number requested if an error occurred.
Remarks:
You should not throw an Exception out of this function.
Purpose:
Read data from a Stream to a buffer.
Access :
Prototype:
void ReadBlock(
void *outBuffer, SInt32 inByteCount); Return:
Purpose:
Access :
Prototype:
SInt32 ReadCString(char *outString)Parameters:
Return:
Returns the number of bytes read.
Remarks:
C string is stored as a 4-byte count followed by the characters. The null terminator is not stored and must be added afterwards.
Purpose:
Read bytes from a Stream to a buffer.
Access :
Prototype:
SInt32 ReadData(
void *outBuffer, SInt32 inByteCount); Return:
Purpose:
Read data from a Stream into a newly created Handle block
Access :
Prototype:
SInt32 ReadHandle(
Handle &outHandle); Return:
Returns the number of bytes read.
Remarks:
A Handle block is stored in a Stream as a 4-byte count (size of the Handle), followed by the contents of the Handle block.
Purpose:
Read a Pascal string from a Stream
Access :
Prototype:
SInt32 ReadPString(
Str255 outString); Return:
Returns the number of bytes read.
Purpose:
Read data from a Stream into a newly created Ptr block
Access :
Prototype:
SInt32 ReadPtr(
Ptr &outPtr); Return:
Returns the number of bytes read.
Remarks:
A Ptr block is stored in a Stream as a 4-byte count (size of the Ptr), followed by the contents of the Ptr block.
Purpose:
Set the length, in bytes, of the Stream.
Access :
Prototype:
void SetLength(
SInt32 inLength; SI
Return:
Purpose:
Place the Read/Write Marker at an offset from a specified position.
inFromWhere can be streamFrom_Start, streamFrom_End, or streamFrom_Marker
Access :
Prototype:
void SetMarker(
SInt32 inOffset, EStreamFrom inFromWhere); Return:
Purpose:
Write data, specified by a pointer and byte count, to a Stream
Access :
Prototype:
void WriteBlock(
const void *inBuffer, SInt32 inByteCount); Return:
Purpose:
Access :
Prototype:
SInt32 WriteCString(
const char *inString); Return:
Returns the number of bytes written.
Remarks:
C string is written as a 4-byte count followed by the characters. The terminater is not written.
Purpose:
Access :
Prototype:
SInt32 WriteData(
const void *inBuffer, SInt32 inByteCount); Return:
Number of bytes actually written.
Remarks:
Purpose:
Write a Toolbox Handle block to a Stream
Access :
Prototype:
SInt32 WriteHandle(
Handle inHandle); Return:
Returns the number of bytes written.
Remarks:
A Handle block is written as a 4-byte count (size of the Handle), followed by the contents of the Handle block.
Purpose:
Write a Pascal string to a Stream.
Access :
Prototype:
SInt32 WritePString(
ConstStringPtr inString); Return:
Returns the number of bytes written.
Purpose:
Write a Toolbox Ptr block to a Stream.
Access :
Prototype:
SInt32 WritePtr(
Ptr inPtr); Return:
Returns the number of bytes written.
Remarks:
A Ptr block is written as a 4-byte count (size of the Ptr), followed by the contents of the Ptr block.
:
LStream& operator << ( TypeParameter )
Type Parameter:
double, float, unsigned long, long, unsigned short, short, char,
unsigned char, signed char, char **, const Point&, const Rect&,
const char*, const unsigned char*, double&, float&, unsigned long&,
long&, unsigned short&, char&, unsigned char&, signed char&, char**&,
Point&, Rect&, char*, unsigned char*
Purpose:
Access :
Prototype:
LStream& operator << (TypeParameter inNum);Parameters:
Return:
LStream& operator >> ( TypeParameter )
Type Parameter:
double, float, unsigned long, long, unsigned short, short, char,
unsigned char, signed char, char **, const Point&, const Rect&,
const char*, const unsigned char*, double&, float&, unsigned long&,
long&, unsigned short&, char&, unsigned char&, signed char&, char**&,
Point&, Rect&, char*, unsigned char*
Purpose:
Access :
Prototype:
LStream& operator >> (TypeParameter inNum);Parameters:
Return:
Purpose:
Access :
Prototype:
LStream& operator = (const LStream& inOriginal);Parameters:
Return:
Returns address of LStream object.
Remarks:
operator = does not create a duplicate of the stream, but assigns a stream the same memory address as the original. If you delete one, you loose both. You have been warned.
Purpose:
Marker position offset in bytes.
Access :
Prototype:
SInt32 mMarker;
Purpose:
Access :
Prototype:
SInt32 mLength;