Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: S32BUF.H
Link against: estor.lib

Class MStreamBuf

class MStreamBuf;

Description

A stream buffer that provides a generic I/O interface for streamed data.

A stream buffer:

may be buffered or unbuffered

may provide read-only, write-only or read/write capability

may be seekable, or unseekable.

A seekable stream buffer maintains independent read and write pointers, which can be manipulated separately. This is unlike the RFile interface which maintains a single current position in the file. For example, file streams and memory streams are seekable streams, but socket, serial-comms, and filtered streams are not.

Objects of this type are used by the stream interface classes derived from RReadStream and RWriteStream.

The class has no member data.

Derive from this class, if the stream has no intermediate buffering capabilities, otherwise derive from TStreamBuf.

Get a reference to the stream buffer used by a read stream by calling RReadStream::Source(). Get a reference to the stream buffer used by a write stream by calling RWriteStream::Sink()

Members

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

See also:


Construction and destruction


MStreamBuf()

protected: inline MStreamBuf();

Description

[Top]


Member functions


Close()

IMPORT_C void Close();

Description

Closes the stream buffer.

This function attempts to synchronise buffered data with the stream before freeing any resources. All errors are ignored.

See also:


Release()

inline void Release();

Description

Frees resources before abandoning the stream buffer.

The function calls the virtual function DoRelease() to implement this behaviour.

Release() is called by both RReadStream::Release() and RWriteStream::Release().

See also:


Synch()

IMPORT_C TInt Synch();

Description

Synchronises the stream buffer with the stream, returning any error.

In effect, this ensures that buffered data is delivered to the stream.

This function calls SynchL() inside a TRAPD harness and returns the leave code if a leave occurs.

Return value

TInt

KErrNone, if successful; otherwise one of the other system wide error codes.

See also:


SynchL()

inline void SynchL();

Description

Synchronises the stream buffer with the stream, leaving if any error occurs.

In effect, this ensures that buffered data is delivered to the stream.

The function calls the virtual function DoSynchL() to implement this behaviour.

See also:


PushL()

IMPORT_C void PushL();

Description

Puts a cleanup item for this object onto the cleanup stack.

This allows allocated resources to be cleaned up if a subsequent leave occurs.


ReadL()

inline TInt ReadL(TAny *aPtr, TInt aMaxLength);

Description

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

The function calls the virtual function DoReadL(TAny*,TInt) to implement this behaviour.

Parameters

TAny *aPtr

A pointer to the target memory location for the data read from the stream buffer.

TInt aMaxLength

The maximum number of bytes to be read.

Return value

TInt

The number of bytes read.

See also:


Read()

IMPORT_C TInt Read(TDes8 &aDes, TRequestStatus &aStatus);

Description

Reads data, asynchronously, from the stream buffer into the specified descriptor; request completion is guaranteed, even if request initiation fails.

The function calls the virtual function DoReadL(TDes8&,TInt,TRequestStatus&) to implement this behaviour. The maximum number of bytes to be read is the value of the maximum length of the descriptor.

Parameters

TDes8 &aDes

The target descriptor for the data read from the stream buffer.

TRequestStatus &aStatus

The request status that indicates the completion status of this asynchronous request.

Return value

TInt

The maximum number of bytes to be read, as used in this request. This value can be different to the maximum length of the descriptor; this is dependent on the implementation.

See also:


Read()

IMPORT_C TInt Read(TDes8 &aDes, TInt aMaxLength, TRequestStatus &aStatus);

Description

Reads data, asynchronously, from the stream buffer into the specified descriptor; request completion is guaranteed, even if request initiation fails.

The function calls the virtual function DoReadL(TDes8&,TInt,TRequestStatus&) to implement this behaviour.

Parameters

TDes8 &aDes

The target descriptor for the data read from the stream buffer.

TInt aMaxLength

The maximum number of bytes to be read.

TRequestStatus &aStatus

The request status that indicates the completion status of this asynchronous request.

Return value

TInt

The maximum number of bytes to be read, as used in this request. This can be different to the value supplied in aMaxLength; this is dependent on the implementation.

See also:


ReadL()

IMPORT_C TInt ReadL(TDes8 &aDes, TRequestStatus &aStatus);

Description

Reads data, asynchronously, from the stream buffer into the specified descriptor.

The function calls the virtual function DoReadL(TDes8&,TInt,TRequestStatus&) to implement this behaviour. The maximum number of bytes to be read is the maximum length of the descriptor.

If the function leaves, then no read request will have been initiated.

Parameters

TDes8 &aDes

The target descriptor for the data read from the stream buffer.

TRequestStatus &aStatus

The request status that indicates the completion status of this asynchronous request.

Return value

TInt

The maximum number of bytes to be read, as used in this request. This value can be different to the maximum length of the descriptor; this is dependent on the implementation.

See also:


ReadL()

inline TInt ReadL(TDes8 &aDes, TInt aMaxLength, TRequestStatus &aStatus);

Description

Reads data, asynchronously, from the stream buffer into the specified descriptor.

The function calls the virtual function DoReadL(TDes8&,TInt,TRequestStatus&) to implement this behaviour.

If the function leaves, then no read request will have been initiated.

Parameters

TDes8 &aDes

The target descriptor for the data read from the stream buffer.

TInt aMaxLength

The maximum number of bytes to be read.

TRequestStatus &aStatus

The request status that indicates the completion status of this asynchronous request.

Return value

TInt

The maximum number of bytes to be read, as used in this request. This can be different to the value supplied in aMaxLength; this is dependent on the implementation.

See also:


ReadL()

inline TStreamTransfer ReadL(MStreamInput &anInput, TStreamTransfer aTransfer);

Description

Reads data from the stream buffer into the specified data sink.

The function calls the virtual function DoReadL(MStreamInput&,TStreamTransfer) to implement this behaviour.

Parameters

MStreamInput &anInput

The data sink that is the target for the read operation.

TStreamTransfer aTransfer

Defines the amount of data available to be read.

Return value

TStreamTransfer

The amount of data that was not consumed.


ReadL()

IMPORT_C TInt ReadL(MStreamInput &anInput, TInt aMaxLength);

Description

Reads data from the stream buffer into the specified data sink.

The function uses the virtual function DoReadL(MStreamInput&,TStreamTransfer) to implement this behaviour.

Parameters

MStreamInput &anInput

The data sink which is the target for the read operation.

TInt aMaxLength

The maximum amount of data available to be read.

Return value

TInt

The amount of data that was not consumed.


ReadL()

inline void ReadL(MStreamInput &anInput);

Description

Reads data from the stream buffer into the specified data sink.

The function uses the virtual function DoReadL(MStreamInput&,TStreamTransfer) to implement this behaviour.

No explicit limit is placed on the amount of data that can be read.

Parameters

MStreamInput &anInput

The data sink that is the target for the read operation.


WriteL()

inline void WriteL(const TAny *aPtr, TInt aLength);

Description

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

The function calls the virtual function DoWriteL(TAny*,TInt) to implement this behaviour.

Parameters

const TAny *aPtr

A pointer to the memory location from which data is to be written to the stream buffer.

TInt aLength

The number of bytes to be written.

See also:


Write()

IMPORT_C TInt Write(const TDesC8 &aDes, TRequestStatus &aStatus);

Description

Writes data, asynchronously, from the specified descriptor into the stream buffer; request completion is guaranteed, even if request initiation fails.

The function calls the virtual function DoWriteL(const TDesC8&,TInt,TRequestStatus&) to implement this behaviour. The maximum number of bytes to be written is the value of the maximum length of the descriptor.

Parameters

const TDesC8 &aDes

The source descriptor for the data to be written into the stream buffer.

TRequestStatus &aStatus

The request status that indicates the completion status of this asynchronous request.

Return value

TInt

The maximum number of bytes to be written, as used in this request. This can be different to the value supplied in aMaxLength; this is dependent on the implementation.

See also:


Write()

IMPORT_C TInt Write(const TDesC8 &aDes, TInt aMaxLength, TRequestStatus &aStatus);

Description

Parameters

const TDesC8 &aDes

TInt aMaxLength

TRequestStatus &aStatus

Return value

TInt


WriteL()

IMPORT_C TInt WriteL(const TDesC8 &aDes, TRequestStatus &aStatus);

Description

Writes data, asynchronously, from the specified descriptor into the stream buffer.

The function calls the virtual function DoWriteL(const TDesC8&,TInt,TRequestStatus&) to implement this behaviour. The maximum number of bytes to be written is the value of the maximum length of the descriptor.

If the function leaves, then no write request will have been initiated.

Parameters

const TDesC8 &aDes

The source descriptor for the data to be written into the stream buffer.

TRequestStatus &aStatus

The request status that indicates the completion status of this asynchronous request.

Return value

TInt

The maximum number of bytes to be written, as used in this request. This can be different to the maximum length of the descriptor; this is dependent on the implementation.

See also:


WriteL()

inline TInt WriteL(const TDesC8 &aDes, TInt aMaxLength, TRequestStatus &aStatus);

Description

Writes data, asynchronously, from the specified descriptor into the stream buffer.

The function calls the virtual function DoWriteL(const TDesC8&,TInt,TRequestStatus&) to implement this behaviour.

If the function leaves, then no write request will have been initiated.

Parameters

const TDesC8 &aDes

The source descriptor for the data to be written into the stream buffer.

TInt aMaxLength

The maximum number of bytes to be written.

TRequestStatus &aStatus

The request status that indicates the completion status of this asynchronous request.

Return value

TInt

The maximum number of bytes to be written, as used in this request. This can be different to the value supplied in aMaxLength; this is dependent on the implementation.

See also:


WriteL()

inline TStreamTransfer WriteL(MStreamOutput &anOutput, TStreamTransfer aTransfer);

Description

Writes data into the stream buffer from the specified data source.

The function calls the virtual function DoWriteL(MStreamOutput&,TStreamTransfer) to implement this behaviour.

Parameters

MStreamOutput &anOutput

The data source for the write operation.

TStreamTransfer aTransfer

Defines the amount of data to be pulled from the output stream object.

Return value

TStreamTransfer

A stream transfer object defining the amount of data that was not consumed.


WriteL()

IMPORT_C TInt WriteL(MStreamOutput &anOutput, TInt aMaxLength);

Description

Writes data into the stream buffer from the specified data source.

The function calls the virtual function DoWriteL(MStreamOutput&,TStreamTransfer) to implement this behaviour.

Parameters

MStreamOutput &anOutput

The data source for the write operation.

TInt aMaxLength

The maximum amount of data available to be written.

Return value

TInt

The amount of data that was not consumed.


WriteL()

inline void WriteL(MStreamOutput &anOutput);

Description

Writes data into the stream buffer from the specified data source.

The function calls the virtual function DoWriteL(MStreamOutput&,TStreamTransfer) to implement this behaviour.

No explicit limit is placed on the amount of data that can be written.

Parameters

MStreamOutput &anOutput

The data source for the write operation.


SeekL()

inline void SeekL(TMark aMark, TStreamPos aPos);

Description

Moves the position of the read or write mark in the stream.

The new position is calculated by adding the specified value to the position of the beginning of the stream.

The function calls virtual function DoSeekL(TMark,TStreamLocation,TInt) to implement this behaviour. Notes: As there are two current positions, one for the read mark and one for the write mark, it is not valid, in general, to use a single call to SeekL() to move both the read and write marks. Not all streams are seekable.

Parameters

TMark aMark

The type of mark, i.e. read or write.

TStreamPos aPos


SeekL()

inline TStreamPos SeekL(TMark aMark, TStreamLocation aLocation, TInt anOffset=0);

Description

Moves the position of the read mark or the write mark in the stream.

The new position is calculated by adding the specified offset to one of:

the position of the beginning of the stream

the position of the end of the stream

the position of the current read mark or write mark.

The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt) to implement this behaviour.

As there are two current positions, one for the read mark and one for the write mark, it is not valid, in general, to use a single call to SeekL() to move both the read and write marks.

Not all streams are seekable.

Parameters

TMark aMark

The type of mark, i.e read or write.

TStreamLocation aLocation

The location in the stream on which the calculation of the new position is based.

TInt anOffset

The offset value.

Return value

TStreamPos

The new stream position of the read or write mark.


SeekL()

inline TStreamPos SeekL(TRead, TStreamLocation aLocation, TInt anOffset=0);

Description

Moves the position of the read mark in the stream.

The new position is calculated by adding the specified offset to one of:

the position of the beginning of the stream

the position of the end of the stream

the position of the current read mark.

The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt) to implement this behaviour.

Not all streams are seekable.

Parameters

TRead

TStreamLocation aLocation

The location in the stream on which the calculation of the new position is based.

TInt anOffset

The offset value.

Return value

TStreamPos

The new stream position of the read mark.


SeekL()

inline TStreamPos SeekL(TWrite, TStreamLocation aLocation, TInt anOffset=0);

Description

Moves the position of the write mark in the stream.

The new position is calculated by adding the specified offset to one of:

the position of the beginning of the stream

the position of the end of the stream

the position of the current write mark.

The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt) to implement this behaviour.

Not all streams are seekable.

Parameters

TWrite

TStreamLocation aLocation

The location in the stream on which the calculation of the new position is based.

TInt anOffset

The offset value.

Return value

TStreamPos

The new stream position of the write mark.


SeekL()

inline TStreamPos SeekL(TRead, TInt anOffset);

Description

Moves the position of the read mark in the stream by the specified offset.

The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt) to implement this behaviour.

Not all streams are seekable.

Parameters

TRead

TInt anOffset

The amount by which the position of the read mark is to be moved relative to the existing position of the read mark.

Return value

TStreamPos

The new stream position of the read mark.


SeekL()

inline TStreamPos SeekL(TWrite, TInt anOffset);

Description

Moves the position of the write mark in the stream by the specified offset.

The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt) to implement this behaviour.

Not all streams are seekable.

Parameters

TWrite

TInt anOffset

The amount by which the position of the write mark is to be moved relative to the existing position of the write mark.

Return value

TStreamPos

The new stream position of the write mark.


TellL()

inline TStreamPos TellL(TRead) const;

Description

Gets the position of the read mark within the stream.

The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt) to implement this behaviour.

Parameters

TRead

Return value

TStreamPos

The stream position.


TellL()

inline TStreamPos TellL(TWrite) const;

Description

Gets the position of the write mark within the stream.

The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt) to implement this behaviour.

Parameters

TWrite

Return value

TStreamPos

The stream position.


SizeL()

inline TInt SizeL() const;

Description

Gets the size of the stream.

Return value

TInt

The size of the stream, in bytes.


DoRelease()

private: virtual IMPORT_C void DoRelease();

Description

Frees resources before abandoning the stream buffer.

It is called by Release().

This implementation is empty, but classes derived from MStreamBuf can provide their own implementation, if necessary.

See also:


DoSynchL()

private: virtual IMPORT_C void DoSynchL();

Description

Synchronises the stream buffer with the stream, leaving if any error occurs.

In effect, this ensures that buffered data is delivered to the stream.

It is called by SynchL().

This implementation is empty, but classes derived from MStreamBuf can provide their own implementation, if necessary.

See also:


DoReadL()

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

Description

Parameters

TAny *aPtr

TInt aMaxLength

Return value

TInt


DoReadL()

private: virtual IMPORT_C TInt DoReadL(TDes8 &aDes, TInt aMaxLength, TRequestStatus &aStatus);

Description

Reads data from the stream buffer into the specified descriptor.

This function is called by ReadL(TDes8&,TInt,TRequestStatus&).

This implementation deals with the request synchronously, and completes the request with KErrNone. Other implementations may choose to deal with this in a true asynchronous manner.

In addition, the read operation itself uses the DoReadL(TAny*,TInt) variant.

Parameters

TDes8 &aDes

The target descriptor for the data read from the stream buffer. On return, the length of the descriptor is set to the number of bytes read from the stream buffer.

TInt aMaxLength

The maximum number of bytes to be read. This value must not be greater than the maximum length of the descriptor, otherwise the function raises a STORE-Stream 2 panic.

TRequestStatus &aStatus

The request status that indicates the completion status of this asynchronous request.

Return value

TInt

The maximum number of bytes to be read, as used in this request. This implementation uses, and returns, the value supplied in aMaxLength. Other implementations may choose to use a different value.

See also:


DoReadL()

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

Description

Reads data from the stream into the specified data sink.

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

This implementation calls the sink's ReadFromL() function, which performs the read (transfer) operation.

This implementation of DoReadL() is called for streams that do not have buffering capabilities, and that are derived directly from this class.

Parameters

MStreamInput &anInput

The target data sink.

TStreamTransfer aTransfer

A stream transfer object defining the amount of data available to be read.

Return value

TStreamTransfer

A stream transfer object defining the amount of data that was not consumed.

See also:


DoWriteL()

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

Description

Parameters

const TAny *aPtr

TInt aLength


DoWriteL()

private: virtual IMPORT_C TInt DoWriteL(const TDesC8 &aDes, TInt aMaxLength, TRequestStatus &aStatus);

Description

Writes data from the specified descriptor into this stream buffer.

This function is called by WriteL(const TDesC8&,TInt,TRequestStatus&).

This implementation deals with the request synchronously, and completes the request with KErrNone. Other implementations may choose to deal with this in a true asynchronous manner.

In addition, the write operation itself uses the DoWriteL(TAny*,TInt) variant.

Parameters

const TDesC8 &aDes

The source descriptor for the data to be written into the stream buffer.

TInt aMaxLength

The number of bytes to be written. This value must not be greater than the maximum length of the descriptor, otherwise the function raises a STORE-Stream 6 panic.

TRequestStatus &aStatus

The request status that indicates the completion status of this asynchronous request.

Return value

TInt

The maximum number of bytes to be written, as used in this request. This implementation uses, and returns, the value supplied in aMaxLength. Other implementations may choose to use a different value.

See also:


DoWriteL()

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

Description

Parameters

MStreamOutput &anOutput

TStreamTransfer aTransfer

Return value

TStreamTransfer


DoSeekL()

private: virtual IMPORT_C TStreamPos DoSeekL(TMark aMark, TStreamLocation aLocation, TInt anOffset);

Description

Parameters

TMark aMark

TStreamLocation aLocation

TInt anOffset

Return value

TStreamPos

[Top]


Member enumerations


Enum TRead

TRead

Description

Indicates that an operation applies to the read mark in a stream or to the read area in an stream buffer.

ERead


Enum TWrite

TWrite

Description

Indicates that an operation applies to the write mark in a stream or to the write area in an stream buffer.

EWrite

[Top]


Member type definitions


Typedef TMark

typedef TInt MStreamBuf::TMark;

Description

Used to identify the type of mark in a stream.

The type is used by functions of this class and derived classes that perform seek operations to marks within a stream.

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

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

See also: