LHandleStream

LHandleStream is a PowerPlant class that is used for doing LStream operations with data blocks that are relocatable, such as handles.

Methods :

The methods in this class are:

LHandleStream()	~LHandleStream()
DetachDataHandle()	GetBytes()
GetDataHandle()	PutBytes()
SetDataHandle()	SetLength()

Data Members:

The data members in this class are:

mDataH

Operation:

General usage for LHandleStream is similar to that of LDataStream and LFileStream.

Source files:

File & Stream Classes)

LHandleStream.h

LHandleStream.cp

Ancestors:

LStream

LHandleStream()

Purpose:

The constructor creates objects.

Access:

Public

Prototype:

LHandleStream();

LHandleStream( Handle inHandle); 

The parameter for the constructors is:

Handle

inHandle

The handle to create an object from.

~LHandleStream()

Purpose:

The destructor destroys the object.

Access:

Virtual, Public

Prototype:

virtual ~LHandleStream();

DetachDataHandle()

Purpose:

Dissociate the data Handle from a HandleStream. This creates a new, empty data Handle and passes back the existing Handle. Caller assumes ownership of the Handle.

Access:

Public

Prototype:

Handle DetachDataHandle();

None

Return:

A new, empty data handle.

GetBytes()

Purpose:

Read bytes from a HandleStream to a buffer.

Access:

Virtual, Public

Prototype:

virtual ExceptionCode GetBytes(

void *outBuffer,

SInt32 &ioByteCount );

The parameters for this method are:

void*	outBuffer	The pointer to a buffer to read into.
SInt32&	ioByteCount	The size of the buffer on input, the number of bytes read on output.

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.

• readErr-Attempt to read past the end of the HandleStream

GetDataHandle()

Purpose:

Retrieves the value of mDataH.

Access:

Public

Prototype:

Handle GetDataHandle();

None

Return:

Returns the value of mDataH.

PutBytes()

Purpose:

Write bytes from a buffer to a HandleStream. Grows the data Handle if necessary.

Access:

Public

Prototype:

virtual ExceptionCode PutBytes(

const void *inBuffer,

SInt32 &ioByteCount );

The parameters for this method are:

const void*	inBuffer	The pointer to a buffer to write into.
SInt32&	ioByteCount	The size of the buffer on input, the number of bytes written on output.

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.

memFullErr-Growing Handle failed when trying to write past the current end of the Stream

SetDataHandle()

Purpose:

Specify a Handle to use as the basis for a HandleStream.

Class assumes ownership of the input Handle and destroys the existing data Handle. Call DetachDataHandle() beforehand if you wish to preserve the existing data Handle.

Access:

Public

Prototype:

void SetDataHandle( Handle inHandle );

The parameter for this method is:

Handle

inHandle

The handle to set for the object.

Return:

None

SetLength()

Purpose:

Set the length, in bytes, of the HandleStream.

Access:

Public

Prototype:

virtual void SetLength( SInt32 inLength );

The parameter for this method is:

SInt32

inLength

The length of the stream.

Return:

None

mDataH

Purpose:

The data handle.

Access:

Protected

Prototype:

Handle mDataH;