Class TStreamBuf

TStreamBuf

Support

Supported from 5.0

Description

Adds buffering capabilities to a stream buffer

The class provides pointers to mark out the current read and write areas within the intermediate buffer. The class also defines the pure virtual functions UnderflowL() and OverflowL() which must be provided by a derived class.

Streams which have buffering capabilities derive from this class, otherwise they derive from MStreamBuf.

Note that the class does not provide the buffer; this is left to the class derived from it. For example, the memory buffer classes use the memory area directly, the file buffer class allocate a heap cell to use as a buffer.

Derivation

MStreamBuf A stream buffer that provides a generic I/O interface for streamed data TStreamBuf Adds buffering capabilities to a stream buffer

Defined in TStreamBuf:
Avail(), DoReadL(), DoWriteL(), End(), OverflowL(), Ptr(), SetBuf(), SetEnd(), SetPtr(), TArea, TStreamBuf(), UnderflowL()

Inherited from MStreamBuf:
SeekL(), Close(), DoRelease(), DoSeekL(), DoSynchL(), ERead, EWrite, PushL(), Read(), ReadL(), Release(), SeekL(), SizeL(), Synch(), SynchL(), TMark, TRead, TWrite, TellL(), Write(), WriteL()

See also:

• UnderflowL()
• OverflowL()

protected : TStreamBuf();

Description

Sets the pointers that mark out the read and write areas within the intermediate buffer to null.

protected : void SetBuf(TArea anArea,TUint8* aPtr,TUint8* anEnd);

Description

Sets the start and end points of the read and/or the write area within the intermediate buffer.

A start point is always within an area; an end point is always the first byte beyond the end of an area.

Parameters

TArea anArea The areas within the intermediate buffer for which the start and end points are to be set. These can be the read area and/or the write area, as indicated by the ERead and EWrite bits. Only these bits can be set, otherwise the function raises a STORE-Stream 17 panic. TUint8* aPtr The start point. TUint8* anEnd The end point.

See also:

• MStreamBuf::TRead
• MStreamBuf::TWrite

protected : void SetBuf(TRead,TUint8* aPtr,TUint8* anEnd);

Description

Sets the start and end points of the read area within the intermediate buffer.

A start point is always within an area; an end point is always the first byte beyond the end of an area.

Parameters

TRead (The enumerator is not used). TUint8* aPtr The start point. TUint8* anEnd The end point.

See also:

• MStreamBuf::TRead

protected : void SetBuf(TWrite,TUint8* aPtr,TUint8* anEnd);

Description

Sets the start and end points of the write area within the intermediate buffer.

A start point is always within an area; an end point is always the first byte beyond the end of an area.

Parameters

TWrite (The enumerator is not used). TUint8* aPtr The start point. TUint8* anEnd The end point.

See also:

• MStreamBuf::TWrite

protected : void SetPtr(TArea anArea,TUint8* aPtr);

Description

Sets the start point of the read and/or the write area within the intermediate buffer.

A start point is always within an area.

Parameters

TArea anArea The areas within the intermediate buffer for which the start point is to be set. These can be the read area and/or the write area, as indicated by the ERead and EWrite bits. Only these bits can be set, otherwise the function raises a STORE-Stream 17 panic. TUint8* aPtr The start point.

See also:

• MStreamBuf::TRead
• MStreamBuf::TWrite

protected : void SetPtr(TRead,TUint8* aPtr);

Description

Sets the start point of the read area within the intermediate buffer.

A start point is always within an area.

Parameters

TRead (The enumerator is not used). TUint8* aPtr1 The start point.

See also:

• MStreamBuf::TRead

protected : void SetPtr(TWrite,TUint8* aPtr);

Description

Sets the start point of the write area within the intermediate buffer.

A start point is always within an area.

Parameters

TWrite (The enumerator is not used). TUint8* aPtr The start point.

See also:

• MStreamBuf::TWrite

protected : void SetEnd(TArea anArea,TUint8* aPtr);

Description

Sets the end point of the read and/or the write area within the intermediate buffer.

An end point is always the first byte beyond the end of an area.

Parameters

TArea anArea The areas within the intermediate buffer for which the end point is to be set. These can be the read area and/or the write area, as indicated by the ERead and EWrite bits. Only these bits can be set, otherwise the function raises a STORE-Stream 17 panic. TUint8* aPtr The end point.

See also:

• MStreamBuf::TRead
• MStreamBuf::TWrite

protected : void SetEnd(TRead,TUint8* anEnd);

Description

Sets the end point of the read area within the intermediate buffer.

An end point is always the first byte beyond the end of an area.

Parameters

TRead (The enumerator is not used). TUint8* aPtr The end point.

See also:

• MStreamBuf::TRead

protected : void SetEnd(TWrite,TUint8* anEnd);

Description

Sets the end point of the write area within the intermediate buffer.

An end point is always the first byte beyond the end of an area.

Parameters

TWrite (The enumerator is not used). TUint8* aPtr The end point.

See also:

• MStreamBuf::TWrite

protected : TUint8* Ptr(TArea anArea) const;

Description

Gets the current start point of the read or write area within the intermediate buffer.

Parameters

TArea anArea The area within the intermediate buffer for which the start point is to be fetched. This can be either the read area or the write area, as indicated by the ERead and EWrite bits. Only one of these can be set, otherwise the function raises a STORE-Stream 17 panic.

Return value

TUint8* The start point.

See also:

• MStreamBuf::TRead
• MStreamBuf::TWrite

protected : TUint8* Ptr(TRead) const;

Description

Gets the current start point of the read area within the intermediate buffer.

Parameters

TRead (The enumerator is not used).

Return value

TUint8* The start point.

See also:

• MStreamBuf::TRead

protected : TUint8* Ptr(TWrite) const;

Description

Gets the current start point of the write area within the intermediate buffer.

Parameters

TWrite (The enumerator is not used).

Return value

TUint8* The start point.

See also:

• MStreamBuf::TWrite

protected : TUint8* End(TArea anArea) const;

Description

Gets the current end point of the read or write area within the intermediate buffer.

An end point is always the first byte beyond the end of an area.

Parameters

TArea anArea The area within the intermediate buffer for which the end point is to be fetched. This can be either the read area or the write area, as indicated by the ERead and EWrite bits. Only one of these can be set, otherwise the function raises a STORE-Stream 17 panic.

Return value

TUint8* The end point.

protected : TUint8* End(TRead) const;

Description

Gets the current end point of the read area within the intermediate buffer.

An end point is always the first byte beyond the end of an area.

Parameters

TRead (The enumerator is not used).

Return value

TUint8* The end point.

See also:

• MStreamBuf::TRead

protected : TUint8* End(TWrite) const;

Description

Gets the current end point of the write area within the intermediate buffer.

An end point is always the first byte beyond the end of an area.

Parameters

TWrite (The enumerator is not used).

Return value

TUint8* The end point.

See also:

• MStreamBuf::TWrite

protected : TInt Avail(TArea anArea) const;

Description

Gets the number of bytes available in the read or write area within the intermediate buffer.

Parameters

TArea anArea The area within the intermediate buffer for which the number of available bytes is to be fetched. This can be either the read area or the write area, as indicated by the ERead and EWrite bits. Only one of these can be set, otherwise the function raises a STORE-Stream 17 panic.

Return value

TInt The number of bytes available.

protected : TInt Avail(TRead) const;

Description

Gets the number of bytes available in the read area within the intermediate buffer.

Parameters

TRead (The enumerator is not used).

Return value

TInt The number of bytes available.

See also:

• MStreamBuf::TRead

protected : TInt Avail(TWrite) const;

Description

Gets the number of bytes available in the write area within the intermediate buffer.

Parameters

TWrite (The enumerator is not used).

Return value

TInt The number of bytes available.

See also:

• MStreamBuf::TWrite

protected : virtual TInt DoReadL(TAny* aPtr,TInt aMaxLength);

Description

Reads data from the intermediate buffer into the specified memory location.

The function calls the virtual function UnderfLowL() to give concrete implementations the chance to refill the intermediate buffer, and satisfy the caller's requirements.

This implementation overrides the one supplied by the base class MStreamBuf, and is called by, MStreamBuf::ReadL(TAny*,TInt).

Parameters

TAny* aPtr A pointer to the target memory location for the data read from the intermediate buffer. TInt aMaxLength The maximum number of bytes to be read.

Return value

TInt The number of bytes read. This may be less than the amount requested.

See also:

• MStreamBuf::ReadL()
• MStreamBuf::DoReadL()

protected : virtual TStreamTransfer DoReadL(MStreamInput& anInput,TStreamTransfer aTransfer);

Description

Reads data from the intermediate buffer and, if necessary, any remaining data from the stream to the specified target stream input object.

It is called by ReadL(MStreamInput&,TStreamTransfer).

The intermediate buffer is emptied first by calling the target stream input's PushL() function, which performs the read from intermediate buffer operation. Any remaining data is then read from the stream by calling the target stream object's ReadFromL() function, which performs the read from stream operation.

Parameters

MStreamInput& anInput The target stream input object. TStreamTransfer aTransfer A stream transfer object defining the amount of data available to be written.

Return value

TStreamTransfer The amount of data that was not consumed.

Notes:

• This implementation is called for streams that have buffering capabilities and are derived from this class.

See also:

• MStreamInput::ReadFromL()
• MStreamInput::PushL()

protected : virtual void DoWriteL(const TAny* aPtr,TInt aLength);

Description

Writes data from the specified memory location into the intermediate buffer.

The function calls the virtual function OverfLowL() to give concrete implementations the chance to forward the intermediate buffer content to its destination.

This implementation overrides the one supplied by the base class MStreamBuf, and is called by MStreamBuf::WriteL(const TAny*,TInt).

Parameters

const TAny* aPtr A pointer to the source memory location for the data to be written to the intermediate buffer. TInt aLength The number of bytes to be written.

Return value

TInt The number of bytes written.

See also:

• MStreamBuf::WriteL()
• MStreamBuf::DoWriteL()

protected : virtual TStreamTransfer DoWriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer);

Description

Writes data to the intermediate buffer and then, if necessary, to the stream from the specified source stream output object.

It is called by WriteL(MStreamOutput&,TStreamTransfer).

The buffer is filled first by calling the source stream output's PullL() function, which performs the write to intermediate buffer operation. Any remaining data is then written to the stream by calling the source stream object's WriteToL() function, which performs the write to stream operation.

Parameters

MStreamOutput& anInput The source stream output object. TStreamTransfer aTransfer A stream transfer object defining the amount of data available to be written.

Return value

TStreamTransfer The amount of data that was not consumed.

Notes:

• This implementation is called for streams that have buffering capabilities and are derived from this class.

See also:

• MStreamOutput::WriteToL()
• MStreamOutput::PullL()

private :    virtual TInt UnderflowL(TInt aMaxLength)=0;

Description

Re-fills the intermediate buffer and resets the start and end points of the read area.

The implementation of this function depends on the way the stream itself is implemented. For example, the in-memory streams have simple implementations.

Parameters

TInt aMaxLength The maximum amount of data required for the intermediate buffer.

Return value

TInt The amount of data available in the intermediate buffer.

private : virtual void OverflowL()=0;

Description

Empties the intermediate buffer and resets the start and end points of the write area.

The implementation of this function depends on the way the stream itself is implemented. For example, the in-memory streams have simple implementations.

typedef TInt TArea;

Description

Used to identify the type of area within an intermediate buffer.

The type is used by functions of this class that set or get pointers into the intermediate buffer.

The type uses the ERead and EWrite enumeration values, as bit flags, to identify the read and write areas respectively.

ERead is an MStreamBuf::TRead enumerator. EWrite is an MStreamBuf::EWrite enumerator.

See also:

• MStreamBuf::TRead
• MStreamBuf::TWrite