Class: TStream

Declaration: Stream.h

Taxonomy Categories:

Member Functions:

~TStream
Flush
GetReadOnly
SetFreezeLevel
GetFreezeLevel
operator>>=
operator<<=
Read
Write
ReadCompressed
WriteCompressed
TStream
operator=
SetBufferWasModified
GetBufferWasModified
GetReadBufferPointer
SetReadBufferPointer
IncrementReadBufferPointer
GetWriteBufferPointer
SetWriteBufferPointer
IncrementWriteBufferPointer
GetLogicalEndOfBuffer
SetLogicalEndOfBuffer
GetPhysicalEndOfBuffer
SetPhysicalEndOfBuffer
SetBuffer
GetStartOfBuffer
GetOffsetOfStartOfBuffer
HandleBufferFull
HandleBufferEmpty
BytesToLong
BytesToShort
BytesToSignedChar
BytesToUnsignedLong
BytesToUnsignedShort
BytesToUnsignedChar
BytesToDouble
BytesToFloat
LongToBytes
ShortToBytes
SignedCharToBytes
UnsignedLongToBytes
UnsignedCharToBytes
DoubleToBytes
FloatToBytes
ReadOneByte
WriteOneByte
ReadTwoBEBytes
WriteTwoBEBytes
ReadFourBEBytes
WriteFourBEBytes
ReadTwoLEBytes
WriteTwoLEBytes
ReadFourLEBytes
WriteFourLEBytes
WriteEightLEBytes
ReadEightLEBytes
WriteEightBEBytes
ReadEightBEBytes
AllocateForRead
AllocateForWrite
SkipReading
UnsignedShortToBytes
HandleWriteBufferFull
HandleReadBufferEmpty
NewWriteFourBEBytes
NewReadFourBEBytes

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TMessageStream TRandomAccessStream

Purpose:

An abstract class that provides operators for reading and writing data structures to and from a stream. A stream is an abstraction that can accept and provide serial binary data. A stream can represent memory, a message stream, a disk file, or other concrete objects.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

TStream is an abstract class and must be derived to be used.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TStream::~TStream

virtual ~ TStream ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Call this function directly to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::Flush

virtual void Flush ()

Interface Category:

API.

Purpose:

Flushes the buffer associated with the stream. This is a virtual function whose behavior is determined by the derived class. If the default class does not define this function, the default behavior does nothing.

Calling Context:

Call this function directly to flush the buffer associated with the stream.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::GetReadOnly

virtual bool GetReadOnly () const

Interface Category:

API.

Purpose:

Returns an indication of whether or not this stream is read-only. If the default class does not define this function, the default behavior is to return false.

Calling Context:

Call this function directly to determine if this stream is read-only.

Parameters:

Takes no parameters.

Return Value:

Returns true if the stream is read-only.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::SetFreezeLevel

void SetFreezeLevel (FreezeLevel theFreezeLevel)

Interface Category:

API.

Purpose:

Sets the freeze level for this object, which determines how much information is placed on the stream when the object is flattened.

Calling Context:

Call this function directly to set the freeze level for this object.

Parameters:

FreezeLevel theFreezeLevel -The freeze level, which is kSameTeam, kSameSession, or kDeepFreeze.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::GetFreezeLevel

FreezeLevel GetFreezeLevel () const

Interface Category:

API.

Purpose:

Returns the freeze level set for this object.

Calling Context:

Call this function directly to return the freeze level set for this object.

Parameters:

Takes no parameters.

Return Value:

The freeze level, which is kSameTeam, kSameSession, or kDeepFreeze.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::operator>>=

virtual TStream & operator >>=(TStream & towhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Call this function directly to stream out data.

Parameters:

TStream & towhere -The stream to which the object streams itself.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::operator<<=

virtual TStream & operator <<= (TStream & towhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Call this function directly to stream in data.

Parameters:

TStream & towhere -The stream from which the object streams itself in.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::Read

TStream & Read (void * addr, size_t howmuch)
TStream & Read (char * c)
TStream & Read (signed char & c)
TStream & Read (unsigned char & c)
TStream & Read (short & c)
TStream & Read (unsigned short & c)
TStream & Read (long & c)
TStream & Read (unsigned long & c)
TStream & Read (float & c)
TStream & Read (double & c)
TStream & Read (signed char c [], size_t count)
TStream & Read (unsigned char c [], size_t count)
TStream & Read (short c [], size_t count)
TStream & Read (unsigned short c [], size_t count)
TStream & Read (long c [], size_t count)
TStream & Read (unsigned long c [], size_t count)
TStream & Read (float c [], size_t count)
TStream & Read (double c [], size_t count)
virtual void Read (TStream & toStream, StreamPosition lengthFromMe)

Interface Category:

API.

Purpose:

All of these operators read specific data types from this stream.

Calling Context:

Each operator is called directly to read a specific data type from this stream.

Parameters:

void * addr -The area to store the untyped data that is read.
size_t howmuch -The number of bytes of untyped data to be read.
char * c -The area to store the char data that is read.
signed char & c -The area to store the signed char data that is read.
unsigned char & c -The area to store the unsigned char data that is read.
short & c -The area to store the short that is read.
unsigned short & c -The area to store the unsigned short that is read.
long & c -The area to store the long that is read.
unsigned long & c -The area to store the unsigned long that is read.
float & c -The area to store the float that is read.
double & c -The area to store the double that is read.
signed char c [] -The area to store the signed chars that are read.
size_t count -The number of signed chars to be read.
unsigned char c [] -The area to store the unsigned chars that are read.
size_t count -The number of unsigned chars to be read.
short c [] -The area to store the shorts that are read.
size_t count -The number of shorts to be read.
unsigned short c [] -The area to store the unsigned shorts that are read.
size_t count -The number of unsigned shorts to be read.
long c [] -The area to store the shorts that are read.
size_t count -The number of longs to be read.
unsigned long c [] -The area to store the unsigned longs that are read.
size_t count -The number of unsigned longs to be read.
float c [] -The area to store the floats that are read.
size_t count -The number of floats to be read.
double c [] -The area to store the doubles that are read.
size_t count -The number of doubles to be read.
TStream & toStream -The stream from which to read.
StreamPosition lengthFromMe -The position in the stream to start reading.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::Write

TStream & Write (const void * addr, size_t howmuch)
TStream & Write (const char * c)
TStream & Write (signed char c)
TStream & Write (unsigned char c)
TStream & Write (short c)
TStream & Write (unsigned short c)
TStream & Write (long c)
TStream & Write (unsigned long c)
TStream & Write (float c)
TStream & Write (double c)
TStream & Write (const signed char c [], size_t count)
TStream & Write (const unsigned char c [], size_t count)
TStream & Write (const short c [], size_t count)
TStream & Write (const unsigned short c [], size_t count)
TStream & Write (const long c [], size_t count)
TStream & Write (const unsigned long c [], size_t count)
TStream & Write (const float c [], size_t count)
TStream & Write (const double c [], size_t count)
virtual void Write (TStream & fromStream, StreamPosition lengthFromStream)

Interface Category:

API.

Purpose:

All of these operators write specific data types to this stream.

Calling Context:

Each operator is called directly to write a specific data type to this stream.

Parameters:

const void * addr -The area where the untyped data to be written is stored.
size_t howmuch -The number of bytes of untyped data to be written.
const char * c -The area where the char to be written is stored.
signed char c -The signed char to be written.
unsigned char c -The unsigned char to be written.
short c -The short to be written.
unsigned short c -The unsigned short to be written.
long c -The long to be written.
unsigned long c -The unsigned long to be written.
float c -The float to be written.
double c -The double to be written.
const signed char c [] -The area where the signed chars to be written are stored.
size_t count -The number of signed chars to be written.
const unsigned char c [] -The area where the unsigned chars to be written are stored.
size_t count -The number of unsigned chars to be written.
const short c [] -The area where the shorts to be written are stored.
size_t count -The number of shorts to be written.
const unsigned short c [] -The area where the unsigned shorts to be written are stored.
size_t count -The number of unsigned shorts to be written.
const long c [] -The area where the longs to be written are stored.
size_t count -The number of longs to be written.
const unsigned long c [] -The area where the unsigned longs to be written are stored.
size_t count -The number of unsigned longs to be written.
const float c [] -The area where the floats to be written are stored.
size_t count -The number of floats to be written.
const double c [] -The area where the doubles to be written are stored.
size_t count -The number of doubles to be written.
TStream & fromStream -The stream to which the data is streamed.
StreamPosition lengthFromStream -The position in the stream to start writing.

Parameters:

TStream & fromStream -The stream to which the data is streamed.
StreamPosition lengthFromStream -The position in the stream to start writing.
const char * -The area where the char to be written is stored.
const void * -The area where the untyped data to be written is stored
size_t -The number of bytes of untyped data to be written.
long -The long to be written.
short -The short to be written.
signed char -The unsigned char to be written.
unsigned long -The unsigned long to be written.
unsigned short -The unsigned short to be written.
unsigned char -The unsigned char to be written.
float -The float to be written.
double -The double to be written.
double * c -The area where the data to be written is stored.
size_t count -The number of doubles to write.
float * c -The area where the data to be written is stored.
size_t count -The number of floats to write.
long * c -The area where the data to be written is stored.
size_t count -The number of longs to write.
unsigned long * c -The area where the data to be written is stored.
size_t count -The number of unsigned longs to write.
short * c -The area where the data to be written is stored.
size_t count -The number of shorts to write.
unsigned short * c -The area where the data to be written is stored.
size_t count -The number of unsigned shorts to write.
signed char * c -The area where the data to be written is stored.
size_t count -The number of signed chars to write.
unsigned char * c -The area where the data to be written is stored.
size_t count -The number of unsigned chars to write.
char -The char to be written.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::ReadCompressed

TStream & ReadCompressed (short & c)
TStream & ReadCompressed (unsigned short & c)
TStream & ReadCompressed (long & c)
TStream & ReadCompressed (unsigned long & c)
TStream & ReadCompressed (float & c)
TStream & ReadCompressed (double & c)

Interface Category:

API.

Purpose:

All of these operators read from this stream a specific data type that has been compressed with WriteCompressed.

Calling Context:

Call this function directly to read a specific data type from the stream and uncompress it.

Parameters:

short & c -The location to store the short that is read.
unsigned short & c -The location to store the unsigned short that is read.
long & c -The location to store the long that is read.
unsigned long & c -The location to store the unsigned long that is read.
float & c -The location to store the float that is read.
double & c -The location to store the double that is read.

Return Value:

Returns a reference to this stream.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::WriteCompressed

TStream & WriteCompressed (short c)
TStream & WriteCompressed (unsigned short c)
TStream & WriteCompressed (long c)
TStream & WriteCompressed (unsigned long c)
TStream & WriteCompressed (float c)
TStream & WriteCompressed (double c)

Interface Category:

API.

Purpose:

All of these operators compress a specific data type and write it to the stream.

Calling Context:

Call this function directly to write a specific data type in a compressed form.

Parameters:

short c -The short to be compressed and written.
unsigned short c -The unsigned short to be compressed and written.
long c -The long to be compressed and written.
unsigned long c -The unsigned long to be compressed and written.
float c -The float to be compressed and written.
double c -The double to be compressed and written.

Return Value:

Returns a reference to this stream.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Data written with WriteCompressed must be read with ReadCompressed.

Member Function: TStream::TStream

TStream (BufferPointer bufferStart, size_t howmuch)
TStream ()
TStream (const TStream & s)

Interface Category:

API.

Purpose:

Creates a stream with the buffer set to the location provided.
Default constructor.
Copy constructor.

Calling Context:

Call this function directly to create a stream with a specified buffer.
Call this function directly anywhere the creation of a TStream is desired.
Call this function directly to copy an object.

Parameters:

BufferPointer bufferStart -The start of the area to use for the stream's buffer.
size_t howmuch -The size of the buffer provided.
Takes no parameters.
const TStream & s -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::operator=

const TStream & operator =(const TStream &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function directly when an object is assigned to another compatible object.

Parameters:

const TStream & -The stream to be copied.

Return Value:

A pointer to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::SetBufferWasModified

void SetBufferWasModified (bool modified =true)

Interface Category:

API.

Purpose:

Sets fBufferModified to the supplied value.

Calling Context:

Call this function directly to set the state of the stream buffer to indicate that it has or has not been modified.

Parameters:

bool modified =true -A flag indicating if the buffer has or has not been modified.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::GetBufferWasModified

bool GetBufferWasModified () const

Interface Category:

API.

Purpose:

Returns the value of fBufferModified.

Calling Context:

Call this function directly to determine if the stream's buffer has been modified.

Parameters:

Takes no parameters.

Return Value:

Returns true if the stream buffer has been modified.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::GetReadBufferPointer

BufferPointer GetReadBufferPointer () const

Interface Category:

API.

Purpose:

Returns the read buffer pointer for this stream.

Calling Context:

Call this function directly to obtain the read buffer pointer for this stream.

Parameters:

Takes no parameters.

Return Value:

A pointer to the read buffer pointer.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::SetReadBufferPointer

void SetReadBufferPointer (BufferPointer readBufferPointer)

Interface Category:

API.

Purpose:

Sets the read buffer pointer for this stream to the specified argument.

Calling Context:

Call this function directly to set the read buffer pointer for this stream.

Parameters:

BufferPointer readBufferPointer -The new pointer value.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::IncrementReadBufferPointer

void IncrementReadBufferPointer (size_t howmuch)

Interface Category:

API.

Purpose:

Increments the read buffer pointer for this stream.

Calling Context:

Call this function directly to adjust this stream's read buffer pointer.

Parameters:

size_t howmuch -The amount to increment the pointer.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::GetWriteBufferPointer

BufferPointer GetWriteBufferPointer () const

Interface Category:

API.

Purpose:

Returns the write buffer pointer for this stream.

Calling Context:

Call this function directly to obtain the write buffer pointer for this stream.

Parameters:

Takes no parameters.

Return Value:

A pointer to the write buffer pointer.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::SetWriteBufferPointer

void SetWriteBufferPointer (BufferPointer writeBufferPointer)

Interface Category:

API.

Purpose:

Sets the write buffer pointer for this stream to the specified argument.

Calling Context:

Call this function directly to set the write buffer pointer for this stream.

Parameters:

BufferPointer writeBufferPointer -The new pointer value.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::IncrementWriteBufferPointer

void IncrementWriteBufferPointer (size_t howmuch)

Interface Category:

API.

Purpose:

Increments the write buffer pointer for this stream.

Calling Context:

Call this function directly to adjust this stream's write buffer pointer.

Parameters:

size_t howmuch -The amount to increment the pointer.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::GetLogicalEndOfBuffer

BufferPointer GetLogicalEndOfBuffer () const

Interface Category:

API.

Purpose:

Returns the logical end of buffer for this stream.

Calling Context:

Call this function directly to get the logical end of buffer.

Parameters:

Takes no parameters.

Return Value:

A pointer to the logical end of buffer.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::SetLogicalEndOfBuffer

void SetLogicalEndOfBuffer (BufferPointer logicalEndOfBufferPointer)

Interface Category:

API.

Purpose:

Sets the logical end of buffer for this stream.

Calling Context:

Call this function directly to set the logical end of buffer.

Parameters:

BufferPointer logicalEndOfBufferPointer -The new logical end of buffer.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::GetPhysicalEndOfBuffer

BufferPointer GetPhysicalEndOfBuffer () const

Interface Category:

API.

Purpose:

Returns the physical end of buffer for this stream.

Calling Context:

Call this function directly to get the physical end of buffer.

Parameters:

Takes no parameters.

Return Value:

A pointer to the physical end of buffer.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::SetPhysicalEndOfBuffer

void SetPhysicalEndOfBuffer (BufferPointer physicalEndOfBufferPointer)

Interface Category:

API.

Purpose:

Sets the physical end of buffer for this stream.

Calling Context:

Call this function directly to set the physical end of buffer.

Parameters:

BufferPointer physicalEndOfBufferPointer -The new physical end of buffer.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::SetBuffer

void SetBuffer (BufferPointer startOfBuffer, StreamPosition offsetOfStart)

Interface Category:

API.

Purpose:

Sets the buffer and buffer offset for this stream.

Calling Context:

Call this function directly to set the buffer and buffer offset for this stream.

Parameters:

BufferPointer startOfBuffer -A reference to the buffer to use.
StreamPosition offsetOfStart -The offset to the start of the buffer.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::GetStartOfBuffer

BufferPointer GetStartOfBuffer () const

Interface Category:

API.

Purpose:

Returns the start of buffer for this stream.

Calling Context:

Call this function directly to obtain the start of buffer for this stream. This is the value that was last passed to the function SetBuffer.

Parameters:

Takes no parameters.

Return Value:

A pointer to the start of the buffer.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::GetOffsetOfStartOfBuffer

StreamPosition GetOffsetOfStartOfBuffer () const

Interface Category:

API.

Purpose:

Returns the start of buffer offset for this stream.

Calling Context:

Call this function directly to obtain the start of buffer offset for this stream. This is the value that was last passed to the function SetBuffer.

Parameters:

Takes no parameters.

Return Value:

A pointer to the offset to the start of buffer.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::HandleBufferFull

virtual void HandleBufferFull (signed char c)
virtual void HandleBufferFull (unsigned char c)
virtual void HandleBufferFull (short c)
virtual void HandleBufferFull (unsigned short c)
virtual void HandleBufferFull (long c)
virtual void HandleBufferFull (unsigned long c)
virtual void HandleBufferFull (float c)
virtual void HandleBufferFull (double c)
virtual void HandleBufferFull (const short c [], size_t count)
virtual void HandleBufferFull (const unsigned short c [], size_t count)
virtual void HandleBufferFull (const long c [], size_t count)
virtual void HandleBufferFull (const unsigned long c [], size_t count)
virtual void HandleBufferFull (const float c [], size_t count)
virtual void HandleBufferFull (const double c [], size_t count)

Interface Category:

API.

Purpose:

All of these member functions handle the buffer full condition for this stream by allocating additional storage for the buffer.

Calling Context:

Call this function directly during write operations when there is no more room in this stream's write buffer.

Parameters:

signed char c -The char to be written.
unsigned char c -The unsigned char to be written.
short c -The short to be written.
unsigned short c -The unsigned short to be written.
long c -The long to be written.
unsigned long c -The unsigned long to be written.
float c -The float to be written.
double c -The double to be written.
const short c [] -The area containing the shorts to be written.
size_t count -The number of shorts to be written.
const unsigned short c [] -The area containing the unsigned shorts to be written.
size_t count -The number of unsigned shorts to be written.
const long c [] -The area containing the longs to be written.
size_t count -The number of longs to be written.
const unsigned long c [] -The area containing the unsigned longs to be written.
size_t count -The number of unsigned longs to be written.
const float c [] -The area containing the floats to be written.
size_t count -The number of floats to be written.
const double c [] -The area containing the doubles to be written.
size_t count -The number of doubles to be written.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::HandleBufferEmpty

virtual void HandleBufferEmpty (signed char & c)
virtual void HandleBufferEmpty (unsigned char & c)
virtual void HandleBufferEmpty (short & c)
virtual void HandleBufferEmpty (unsigned short & c)
virtual void HandleBufferEmpty (long & c)
virtual void HandleBufferEmpty (unsigned long & c)
virtual void HandleBufferEmpty (float & c)
virtual void HandleBufferEmpty (double & c)
virtual void HandleBufferEmpty (short c [], size_t count)
virtual void HandleBufferEmpty (unsigned short c [], size_t count)
virtual void HandleBufferEmpty (long c [], size_t count)
virtual void HandleBufferEmpty (unsigned long c [], size_t count)
virtual void HandleBufferEmpty (float c [], size_t count)
virtual void HandleBufferEmpty (double c [], size_t count)

Interface Category:

API.

Purpose:

All of these member functions handle the buffer empty condition for this stream by reading more of the appropriate type of data from the stream into the buffer.

Calling Context:

Call this function directly during read operations when the buffer for this stream is empty.

Parameters:

signed char & c -The area to store the signed char to be read.
unsigned char & c -The area to store the unsigned char to be read.
short & c -The area to store the short to be read.
unsigned short & c -The area to store the unsigned char to be read.
long & c -The area to store the long to be read.
unsigned long & c -The area to store the unsigned long to be read.
float & c -The area to store the float to be read.
double & c -The area to store the double to be read.
short c [] -The area to store the shorts to be read.
size_t count -The number of shorts to read.
unsigned short c [] -The area to store the unsigned shorts to be read.
size_t count -The number of unsigned shorts to read.
long c [] -The area to store the longs to be read.
size_t count -The number of longs to read.
unsigned long c [] -The area to store the unsigned longs to be read.
size_t count -The number of unsigned longs to read.
float c [] -The area to store the floats to be read.
size_t count -The number of floats to read.
double c [] -The area to store the doubles to be read.
size_t count -The number of doubles to read.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::BytesToLong

static long BytesToLong (const void * addr)

Interface Category:

API.

Purpose:

Converts a string of bytes in memory to a long.

Calling Context:

Call this function directly to convert a string of bytes to a long.

Parameters:

const void * addr -The location of the bytes to be converted.

Return Value:

The converted long value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The data to be converted should be aligned according to rules of your platform's architecture.

Member Function: TStream::BytesToShort

static short BytesToShort (const void * addr)

Interface Category:

API.

Purpose:

Converts a string of bytes in memory to a short.

Calling Context:

Call this function directly to convert a string of bytes to a short.

Parameters:

const void * addr -The location of the bytes to be converted.

Return Value:

The converted short value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The data to be converted should be aligned according to rules of your platform's architecture.

Member Function: TStream::BytesToSignedChar

static signed char BytesToSignedChar (const void * addr)

Interface Category:

API.

Purpose:

Converts a string of bytes in memory to a signed char.

Calling Context:

Call this function directly to convert a bytes to a signed char.

Parameters:

const void * addr -The location of the bytes to be converted.

Return Value:

The converted signed char value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::BytesToUnsignedLong

static unsigned long BytesToUnsignedLong (const void * addr)

Interface Category:

API.

Purpose:

Converts a string of bytes in memory to an unsigned long.

Calling Context:

Call this function directly to convert a string of bytes to an unsigned long.

Parameters:

const void * addr -The location of the bytes to be converted.

Return Value:

The converted unsigned long value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The data to be converted should be aligned according to rules of your platform's architecture.

Member Function: TStream::BytesToUnsignedShort

static unsigned short BytesToUnsignedShort (const void * addr)

Interface Category:

API.

Purpose:

Converts a string of bytes in memory to an unsigned short.

Calling Context:

Call this function directly to convert a string of bytes to an unsigned short.

Parameters:

const void * addr -The location of the bytes to be converted.

Return Value:

The converted unsigned short value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The data to be converted should be aligned according to rules of your platform's architecture.

Member Function: TStream::BytesToUnsignedChar

static unsigned char BytesToUnsignedChar (const void * addr)

Interface Category:

API.

Purpose:

Converts a string of bytes in memory to an unsigned char.

Calling Context:

Call this function directly to convert a byte to an unsigned char.

Parameters:

const void * addr -The location of the bytes to be converted.

Return Value:

The converted long value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::BytesToDouble

static double BytesToDouble (const void * addr)

Interface Category:

API.

Purpose:

Converts a string of bytes in memory to a double.

Calling Context:

Call this function directly to convert a string of bytes to a double.

Parameters:

const void * addr -The location of the bytes to be converted.

Return Value:

The converted double value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The data to be converted should be aligned according to rules of your platform's architecture.

Member Function: TStream::BytesToFloat

static float BytesToFloat (const void * addr)

Interface Category:

API.

Purpose:

Converts a string of bytes in memory to a float.

Calling Context:

Call this function directly to convert a string of bytes to a float.

Parameters:

const void * addr -The location of the bytes to be converted.

Return Value:

The converted float value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The data to be converted should be aligned according to rules of your platform's architecture.

Member Function: TStream::LongToBytes

static void LongToBytes (void * addr, long c)

Interface Category:

API.

Purpose:

Converts a long to a sequence of bytes in memory.

Calling Context:

Call this function directly to convert a long to a sequence of bytes.

Parameters:

const void * addr -The location to store the converted bytes.
long c -The value to convert.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::ShortToBytes

static void ShortToBytes (void * addr, short c)

Interface Category:

API.

Purpose:

Converts a short to a sequence of bytes in memory.

Calling Context:

Call this function directly to convert a short to a sequence of bytes.

Parameters:

const void * addr -The location to store the converted bytes.
short c -The value to convert.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::SignedCharToBytes

static void SignedCharToBytes (void * addr, signed char c)

Interface Category:

API.

Purpose:

Converts a signed char to a sequence of bytes in memory.

Calling Context:

Call this function directly to convert a signed char to a sequence of bytes.

Parameters:

const void * addr -The location to store the converted bytes.
signed char c -The value to convert.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::UnsignedLongToBytes

static void UnsignedLongToBytes (void * addr, unsigned long c)

Interface Category:

API.

Purpose:

Converts an unsigned long to a sequence of bytes in memory.

Calling Context:

Call this function directly to convert an unsigned long to a sequence of bytes.

Parameters:

const void * addr -The location to store the converted bytes.
unsigned long c -The value to convert.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::UnsignedCharToBytes

static void UnsignedCharToBytes (void * addr, unsigned char c)

Interface Category:

API.

Purpose:

Converts an unsigned char to a sequence of bytes in memory.

Calling Context:

Call this function directly to convert an unsigned char to a sequence of bytes.

Parameters:

const void * addr -The location to store the converted bytes.
unsigned char c -The value to convert.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::DoubleToBytes

static void DoubleToBytes (void * addr, double c)

Interface Category:

API.

Purpose:

Converts a double to a sequence of bytes in memory.

Calling Context:

Call this function directly to convert a double to a sequence of bytes.

Parameters:

const void * addr -The location to store the converted bytes.
double c -The value to convert.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::FloatToBytes

static void FloatToBytes (void * addr, float c)

Interface Category:

API.

Purpose:

Converts a float to a sequence of bytes in memory.

Calling Context:

Call this function directly to convert a float to a sequence of bytes.

Parameters:

void * addr -The location to store the converted bytes.
float c -The value to convert.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::ReadOneByte

static unsigned char ReadOneByte (const void * addr)

Interface Category:

API.

Purpose:

Reads one byte.

Calling Context:

Call this function directly to read one byte.

Parameters:

const void * addr -The location to read.

Return Value:

The byte read.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::WriteOneByte

static void WriteOneByte (void * addr, unsigned char c)

Interface Category:

API.

Purpose:

Writes one byte.

Calling Context:

Call this function directly to write one byte.

Parameters:

void * addr -The location to be written.
unsigned char c -The byte to write.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::ReadTwoBEBytes

static unsigned short ReadTwoBEBytes (const void * addr)

Interface Category:

API.

Purpose:

Reads two big endian aligned bytes from this specified location.

Calling Context:

Call this function directly to read two bytes stored in big endian representation.

Parameters:

const void * addr -The area from which the bytes are read.

Return Value:

The two bytes as an unsigned short.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::WriteTwoBEBytes

static void WriteTwoBEBytes (void * addr, unsigned short c)

Interface Category:

API.

Purpose:

Writes two big endian aligned bytes.

Calling Context:

Call this function directly to write two big endian bytes.

Parameters:

void * addr -The area where the bytes are to be written.
unsigned short c -The two bytes.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::ReadFourBEBytes

static unsigned long ReadFourBEBytes (const void * addr)

Interface Category:

API.

Purpose:

Reads four big endian aligned bytes from this specified location.

Calling Context:

Call this function directly to read four bytes stored in big endian representation.

Parameters:

const void * addr -The area from which the bytes are read.

Return Value:

The four bytes as an unsigned long.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::WriteFourBEBytes

static void WriteFourBEBytes (void * addr, unsigned long c)

Interface Category:

API.

Purpose:

Writes four big endian aligned bytes.

Calling Context:

Call this function directly to write four big endian bytes.

Parameters:

void * addr -The area where the bytes are to be written.
unsigned long c -The four bytes.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::ReadTwoLEBytes

static unsigned short ReadTwoLEBytes (const void * addr)

Interface Category:

API.

Purpose:

Reads two little endian aligned bytes from this specified location.

Calling Context:

Call this function directly to read two bytes stored in little endian representation.

Parameters:

const void * addr -The area from which the bytes are read.

Return Value:

The two bytes as an unsigned short.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::WriteTwoLEBytes

static void WriteTwoLEBytes (void * addr, unsigned short c)

Interface Category:

API.

Purpose:

Writes two little endian aligned bytes.

Calling Context:

Call this function directly to write two little endian bytes.

Parameters:

void * addr -The area where the bytes are to be written.
unsigned short c -The two bytes.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::ReadFourLEBytes

static unsigned long ReadFourLEBytes (const void * addr)

Interface Category:

API.

Purpose:

Reads four little endian aligned bytes from this specified location.

Calling Context:

Call this function directly to read four bytes stored in little endian representation.

Parameters:

const void * addr -The area from which the bytes are read.

Return Value:

The four bytes as an unsigned long.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::WriteFourLEBytes

static void WriteFourLEBytes (void * addr, unsigned long c)

Interface Category:

API.

Purpose:

Writes four little endian aligned bytes.

Calling Context:

Call this function directly to write four little endian bytes.

Parameters:

void * addr -The area where the bytes are to be written.
unsigned long c -The four bytes.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::WriteEightLEBytes

static void WriteEightLEBytes (void * addr, double c)

Interface Category:

API.

Purpose:

Writes eight little endian aligned bytes.

Calling Context:

Call this function directly to write eight little endian bytes.

Parameters:

void * addr -The area where the bytes are to be written.
double c -The eight bytes.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::ReadEightLEBytes

static double ReadEightLEBytes (const void * addr)

Interface Category:

API.

Purpose:

Reads eight little endian aligned bytes from this specified location.

Calling Context:

Call this function directly to read eight bytes stored in little endian representation.

Parameters:

const void * addr -The area from which the bytes are read.

Return Value:

The eight bytes as a double.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::WriteEightBEBytes

static void WriteEightBEBytes (void * addr, double c)

Interface Category:

API.

Purpose:

Writes eight big endian aligned bytes.

Calling Context:

Call this function directly to write eight big endian bytes.

Parameters:

void * addr -The area where the bytes are to be written.
double c -The eight bytes.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::ReadEightBEBytes

static double ReadEightBEBytes (const void * addr)

Interface Category:

API.

Purpose:

Reads eight big endian aligned bytes from this specified location.

Calling Context:

Call this function directly to read eight bytes stored in big endian representation.

Parameters:

const void * addr -The area from which the bytes are read.

Return Value:

The eight bytes as a double.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::AllocateForRead

virtual void AllocateForRead (StreamPosition desiredByteCount)

Interface Category:

API.

Purpose:

Pure virtual function for increasing the storage provided by the read buffer. The behavior of this operator is defined by the derived class.

Calling Context:

Call this function directly to increase the storage provided by the read buffer.

Parameters:

StreamPosition desiredByteCount -The number of bytes needed in the read buffer.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::AllocateForWrite

virtual void AllocateForWrite (StreamPosition desiredByteCount)

Interface Category:

API.

Purpose:

A pure virtual function for increasing the storage provided by the write buffer. The behavior of this operator is defined by the derived class.

Calling Context:

Call this function directly to increase the storage provided by the write buffer.

Parameters:

StreamPosition desiredByteCount -The number of bytes needed in the write buffer.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::SkipReading

virtual void SkipReading (StreamPosition bytesToSkip)

Interface Category:

API.

Purpose:

Moves ahead in the read buffer by the specified number of bytes. AllocateForWrite is called if the number of bytes to skip goes beyond what is in the buffer.

Calling Context:

Call this function directly to skip ahead in the read buffer.

Parameters:

StreamPosition bytesToSkip -The number of bytes to skip.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If the read buffer size must be increased, the function AllocateForRead is called.

Member Function: TStream::UnsignedShortToBytes

static void UnsignedShortToBytes (void * addr, unsigned short c)

Interface Category:

API.

Purpose:

Converts an unsigned short to a sequence of bytes in memory.

Calling Context:

Call this function directly to convert an unsigned short to a sequence of bytes.

Parameters:

const void * addr -The location to store the converted bytes.
unsigned short c -The value to convert.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStream::HandleWriteBufferFull

virtual void HandleWriteBufferFull (const void * c, size_t len)

Interface Category:

API.

Purpose:

Handle writing of data when the data is in Taligent canonical format but won't fit in this stream's write buffer.

Calling Context:

Call this function directly during write operations when data which is in Taligent canonical format is ready to be written but won't fit in this stream's write buffer.

Parameters:

const void * c -Address of the data to be written.
size_t len -Size of the data to be written.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function can be overridden by derived classes to detect writes of large amounts of data and handle it without moving it to the buffer. It can also be used to implement a derived class of TStream which has no internal buffer.

Member Function: TStream::HandleReadBufferEmpty

virtual void HandleReadBufferEmpty (void * c, size_t len)

Interface Category:

API.

Purpose:

Handle reading of data when the data is in Taligent canonical format but isn't available in this stream's read buffer.

Calling Context:

Call this function directly during read operations when data which is in Taligent canonical format needs to be read but isn't available in this stream's write buffer.

Parameters:

void * c -Address of where the data is to be read.
size_t len -Size of the data to be read.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function can be overridden by derived classes to detect reads of large amounts of data and handle it without moving it from the buffer. It can also be used to implement a derived class of TStream which has no internal buffer.

Member Function: TStream::NewWriteFourBEBytes

static void NewWriteFourBEBytes (void * intoBuffer, void * dataFrom)

Interface Category:

API.

Purpose:

Writes four big endian aligned bytes.

Calling Context:

Call this function directly to write four big endian bytes.

Parameters:

void * intoBuffer -The area to where the bytes are written.
void * dataFrom -The area from which the bytes are read.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is similar to function WriteFourBEBytes, but does not have a problem with optimization.

Member Function: TStream::NewReadFourBEBytes

static void NewReadFourBEBytes (const void * readFrom, void * writeTo)

Interface Category:

API.

Purpose:

Reads four big endian aligned bytes from this specified location.

Calling Context:

Call this function directly to read four bytes stored in big endian representation.

Parameters:

const void * readFrom -The area from which the bytes are read.
void * writeTo -The area to where the bytes are written.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is similar to function ReadFourBEBytes, but does not have a problem with optimization.

Click the icon to mail questions or corrections about this material to Taligent personnel.