MStreamBuf Class Reference

#include <s32buf.h>

class MStreamBuf

Public Member Type Definitions
typedef	TInt TMark

Public Member Enumerations
enum	TRead { ERead }
enum	TWrite { EWrite }

Public Member Functions
IMPORT_C void	Close()
IMPORT_C void	PushL()
IMPORT_C TInt	Read(TDes8 &, TRequestStatus &)
IMPORT_C TInt	Read(TDes8 &, TInt, TRequestStatus &)
TInt	ReadL(TAny *, TInt)
IMPORT_C TInt	ReadL(TDes8 &, TRequestStatus &)
TInt	ReadL(TDes8 &, TInt, TRequestStatus &)
TStreamTransfer	ReadL(MStreamInput &, TStreamTransfer)
IMPORT_C TInt	ReadL(MStreamInput &, TInt)
void	ReadL(MStreamInput &)
void	Release()
void	SeekL(TMark, TStreamPos)
TStreamPos	SeekL(TMark, TStreamLocation, TInt)
TStreamPos	SeekL(TRead, TStreamLocation, TInt)
TStreamPos	SeekL(TWrite, TStreamLocation, TInt)
TStreamPos	SeekL(TRead, TInt)
TStreamPos	SeekL(TWrite, TInt)
TInt	SizeL()
IMPORT_C TInt	Synch()
void	SynchL()
TStreamPos	TellL(TRead)
TStreamPos	TellL(TWrite)
IMPORT_C TInt	Write(const TDesC8 &, TRequestStatus &)
IMPORT_C TInt	Write(const TDesC8 &, TInt, TRequestStatus &)
void	WriteL(const TAny *, TInt)
IMPORT_C TInt	WriteL(const TDesC8 &, TRequestStatus &)
TInt	WriteL(const TDesC8 &, TInt, TRequestStatus &)
TStreamTransfer	WriteL(MStreamOutput &, TStreamTransfer)
IMPORT_C TInt	WriteL(MStreamOutput &, TInt)
void	WriteL(MStreamOutput &)

Protected Member Functions
	MStreamBuf()

Detailed 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()

Member Type Definition Documentation

Typedef TMark

typedef TInt

TMark

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.

Member Enumeration Documentation

Enum TRead

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

Enumerator	Value	Description
ERead	0x01

Enum TWrite

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

Enumerator	Value	Description
EWrite	0x02

Constructor & Destructor Documentation

MStreamBuf ( )

MStreamBuf

(

)

[protected, inline]

Member Function Documentation

Close ( )

IMPORT_C void

(

)

Closes the stream buffer.

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

PushL ( )

IMPORT_C void

PushL

(

)

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

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

Read ( TDes8 &, TRequestStatus & )

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

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.

See also: MStreamBuf::DoReadL()

Parameters
aDes	The target descriptor for the data read from the stream buffer.
aStatus	The request status that indicates the completion status of this asynchronous request.

Return Value: 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.

Read ( TDes8 &, TInt, TRequestStatus & )

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

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.

See also: MStreamBuf::DoReadL()

Parameters
aDes	The target descriptor for the data read from the stream buffer.
aMaxLength	The maximum number of bytes to be read.
aStatus	The request status that indicates the completion status of this asynchronous request.

Return Value: 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.

ReadL ( TAny *, TInt )

TInt	ReadL	(	TAny *	aPtr,
			TInt	aMaxLength
		)	[inline]

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

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

See also: MStreamBuf::DoReadL()

Parameters
aPtr	A pointer to the target memory location for the data read from the stream buffer.
aMaxLength	The maximum number of bytes to be read.

Return Value: The number of bytes read.

ReadL ( TDes8 &, TRequestStatus & )

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

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.

See also: MStreamBuf::DoReadL()

Parameters
aDes	The target descriptor for the data read from the stream buffer.
aStatus	The request status that indicates the completion status of this asynchronous request.

Return Value: 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.

ReadL ( TDes8 &, TInt, TRequestStatus & )

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

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.

See also: MStreamBuf::DoReadL()

Parameters
aDes	The target descriptor for the data read from the stream buffer.
aMaxLength	The maximum number of bytes to be read.
aStatus	The request status that indicates the completion status of this asynchronous request.

Return Value: 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.

ReadL ( MStreamInput &, TStreamTransfer )

TStreamTransfer	ReadL	(	MStreamInput &	anInput,
			TStreamTransfer	aTransfer
		)	[inline]

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
anInput	The data sink that is the target for the read operation.
aTransfer	Defines the amount of data available to be read.

Return Value: The amount of data that was not consumed.

ReadL ( MStreamInput &, TInt )

IMPORT_C TInt	ReadL	(	MStreamInput &	anInput,
			TInt	aMaxLength
		)

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
anInput	The data sink which is the target for the read operation.
aMaxLength	The maximum amount of data available to be read.

Return Value: The amount of data that was not consumed.

ReadL ( MStreamInput & )

void

ReadL

(

MStreamInput &

anInput

)

[inline]

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
anInput	The data sink that is the target for the read operation.

Release ( )

void

Release

(

)

[inline]

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: MStreamBuf::DoRelease() RReadStream::Release() RWriteStream::Release()

SeekL ( TMark, TStreamPos )

void	SeekL	(	TMark	aMark,
			TStreamPos	aPos
		)	[inline]

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
aMark	The type of mark, i.e. read or write.

SeekL ( TMark, TStreamLocation, TInt )

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

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
aMark	The type of mark, i.e read or write.
aLocation	The location in the stream on which the calculation of the new position is based.
anOffset	The offset value.

Return Value: The new stream position of the read or write mark.

SeekL ( TRead, TStreamLocation, TInt )

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

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
aLocation	The location in the stream on which the calculation of the new position is based.
anOffset	The offset value.

Return Value: The new stream position of the read mark.

SeekL ( TWrite, TStreamLocation, TInt )

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

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
aLocation	The location in the stream on which the calculation of the new position is based.
anOffset	The offset value.

Return Value: The new stream position of the write mark.

SeekL ( TRead, TInt )

TStreamPos	SeekL	(	TRead	,
			TInt	anOffset
		)	[inline]

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
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: The new stream position of the read mark.

SeekL ( TWrite, TInt )

TStreamPos	SeekL	(	TWrite	,
			TInt	anOffset
		)	[inline]

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
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: The new stream position of the write mark.

SizeL ( )

TInt

SizeL

(

)

const [inline]

Gets the size of the stream.

Return Value: The size of the stream, in bytes.

Synch ( )

IMPORT_C TInt

Synch

(

)

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.

See also: MStreamBuf::SynchL() MStreamBuf::DoSynchL()

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

SynchL ( )

void

SynchL

(

)

[inline]

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.

TellL ( TRead )

TStreamPos

TellL

(

TRead

)

const [inline]

Gets the position of the read mark within the stream.

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

Return Value: The stream position.

TellL ( TWrite )

TStreamPos

TellL

(

TWrite

)

const [inline]

Gets the position of the write mark within the stream.

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

Return Value: The stream position.

Write ( const TDesC8 &, TRequestStatus & )

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

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.

See also: MStreamBuf::DoWriteL()

Parameters
aDes	The source descriptor for the data to be written into the stream buffer.
aStatus	The request status that indicates the completion status of this asynchronous request.

Return Value: 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.

Write ( const TDesC8 &, TInt, TRequestStatus & )

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

WriteL ( const TAny *, TInt )

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

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

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

See also: MStreamBuf::DoWriteL()

Parameters
aPtr	A pointer to the memory location from which data is to be written to the stream buffer.
aLength	The number of bytes to be written.

WriteL ( const TDesC8 &, TRequestStatus & )

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

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

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

See also: MStreamBuf::DoWriteL()

Parameters
aDes	The source descriptor for the data to be written into the stream buffer.
aStatus	The request status that indicates the completion status of this asynchronous request.

Return Value: 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.

WriteL ( const TDesC8 &, TInt, TRequestStatus & )

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

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.

See also: MStreamBuf::DoWriteL()

Parameters
aDes	The source descriptor for the data to be written into the stream buffer.
aMaxLength	The maximum number of bytes to be written.
aStatus	The request status that indicates the completion status of this asynchronous request.

Return Value: 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.

WriteL ( MStreamOutput &, TStreamTransfer )

TStreamTransfer	WriteL	(	MStreamOutput &	anOutput,
			TStreamTransfer	aTransfer
		)	[inline]

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
anOutput	The data source for the write operation.
aTransfer	Defines the amount of data to be pulled from the output stream object.

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

WriteL ( MStreamOutput &, TInt )

IMPORT_C TInt	WriteL	(	MStreamOutput &	anOutput,
			TInt	aMaxLength
		)

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
anOutput	The data source for the write operation.
aMaxLength	The maximum amount of data available to be written.

Return Value: The amount of data that was not consumed.

WriteL ( MStreamOutput & )

void

WriteL

(

MStreamOutput &

anOutput

)

[inline]

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
anOutput	The data source for the write operation.