Class TStreamMark

TStreamMark

Support

Supported from 5.0

Description

Manages the position of a read mark or a write mark within a shared stream.

A shared stream is one that shares its host with other streams. In practice, the host is a stream buffer that is, itself, hosted by a file, an RFileBuf object.

TStreamMark objects are owned by RShareBuf, one for reading and one for writing. They re-direct read/write operations through a TStreamExchange object to the RFileBuf object, which handles the actual file read and write operations.

Defined in TStreamMark:
SeekL(), Clear(), ExtractL(), IsEmpty(), IsWith(), Position(), ReadL(), RelatesTo(), SeekL(), TStreamMark(), TellL(), Withdraw(), WriteL(), operator TStreamMark*(), operator!=(), operator=(), operator==()

See also:

• RFileBuf
• RShareBuf
• TStreamExchange

TStreamMark();

Description

Constructs a default shared stream mark object.

The position for the mark is uninitialised.

Notes:

• An uninitialised mark means that a call to IsEmpty() returns true.

See also:

• IsEmpty()

TStreamMark(TStreamPos aPos);

Description

Constructs the shared stream mark object, setting the mark to the specified stream position.

Parameters

TStreamPos aPos The stream position

Notes:

• An initialised mark means that a call to IsEmpty() returns false.

See also:

• IsEmpty()

TInt ReadL(TStreamExchange& aHost,TAny* aPtr,TInt aMaxLength);

Description

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

Parameters

TStreamExchange& aHost The object that manages shared streaming. TAny* aPtr A pointer to the target memory location for the data read from the shared stream. TInt aMaxLength The maximum number of bytes to be read.

Return value

TInt The number of bytes read.

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

Description

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

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

Parameters

TStreamExchange& aHost The object that manages shared streaming. TDes8& aDes The target descriptor for the data read from the shared stream. 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 of the underlying stream.

TInt ReadL(TStreamExchange& aHost,TDes8& aDes,TRequestStatus& aStatus);

Description

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

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

Parameters

TStreamExchange& aHost The object that manages shared streaming. TDes8& aDes The target descriptor for the data read from the shared stream.

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 of the underlying stream.

TStreamTransfer ReadL(TStreamExchange& aHost,MStreamInput& anInput,TStreamTransfer aTransfer);
    

Description

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

Parameters

TStreamExchange& aHost The object that manages shared streaming. MStreamInput& anInput The sink which is the target for the read operation. TStreamTransfer aTransfer Defines the amount of data available to be read from the shared stream.

Return value

TStreamTransfer The amount of data that was not consumed.

TInt ReadL(TStreamExchange& aHost,MStreamInput& anInput,TInt aMaxLength);

Description

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

Parameters

TStreamExchange& aHost The object that manages shared streaming. MStreamInput& anInput The sink which is the target for the read operation. TInt aMaxLength The maximum amount of data available to be read from the shared stream.

Return value

TInt The amount of data that was not consumed.

void ReadL(TStreamExchange& aHost,MStreamInput& anInput);

Description

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

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

Parameters

TStreamExchange& aHost The object that manages shared streaming. MStreamInput& anInput The sink which is the target for the read operation.

void WriteL(TStreamExchange& aHost,const TAny* aPtr,TInt aLength);

Description

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

Parameters

TStreamExchange& aHost The object that manages shared streaming. const TAny* aPtr A pointer to the memory location from which data is to be written to the shared stream. TInt aLength The number of bytes to be written.

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

Description

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

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

Parameters

TStreamExchange& aHost The object that manages shared streaming. const TDesC8& aDes The source descriptor for the data to be written into the shared stream. 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.

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

Description

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

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

TStreamExchange& aHost The object that manages shared streaming. const TDesC8& aDes The source descriptor for the data to be written into the shared stream. 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.

TStreamTransfer WriteL(TStreamExchange& aHost,MStreamOutput& anOutput,TStreamTransfer aTransfer);
    

Description

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

Parameters

TStreamExchange& aHost The object that manages shared streaming. 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.

TInt WriteL(TStreamExchange& aHost,MStreamOutput& anOutput,TInt aMaxLength);

Description

Writes data into the shared stream from the specified data source

Parameters

TStreamExchange& aHost The object that manages shared streaming. 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.

void WriteL(TStreamExchange& aHost,MStreamOutput& anOutput);

Description

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

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

Parameters

TStreamExchange& aHost The object that manages shared streaming. MStreamOutput& anOutput The data source for the write operation.

void SeekL(TStreamExchange& aHost,TStreamPos aPos);

Description

Moves the position of the mark in the host stream.

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

Parameters

TStreamExchange& aHost The object that manages shared streaming. TStreamPos aLocation A stream position value on which the calculation of the new position is based.

TStreamPos SeekL(TStreamExchange& aHost,TStreamLocation aLocation,TInt anOffset=0);

Description

Moves the position of the mark in the host stream.

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

• the position of the beginning of the host stream

• the position of the end of the host stream

• the position of the current mark.

Parameters

TStreamExchange& aHost The object that manages shared streaming. TStreamLocation aLocation The location in the host stream on which the calculation of the new position is based. TInt anOffset The offset value.

Return value

TStreamPos The new position of the mark.

TStreamPos SeekL(TStreamExchange& aHost,TInt anOffset);

Description

Moves the position of the mark in the host stream.

Parameters

TStreamExchange& aHost The object that manages shared streaming. TInt anOffset The amount by which the position of the mark is to be moved relative to the existing position of the mark.

Return value

TStreamPos The new position of the mark.

TBool IsEmpty() const;

Description

Tests whether this mark object is uninitialised.

Return value

TBool True, if this mark object is uninitialised; false, otherwise.

TBool IsWith(TStreamExchange& aHost) const;

Description

Tests whether the specified shared streaming manager currently refers to this mark object.

Parameters

TStreamExchange& aHost The object that manages shared streaming.

Return value

TBool True, if the shared stream manager refers to this mark; false, otherwise.

TBool RelatesTo(TStreamExchange& aHost) const;

Description

Tests whether the specified shared streaming manager currently refers to this mark object OR whether this mark object is initialised.

Parameters

TStreamExchange& aHost The object that manages shared streaming.

Return value

TBool True, if the shared stream manager refers to this mark OR if this mark object is initialised; false, otherwise.

See also:

• IsWith()
• TStreamExchange::IsActive()

TStreamPos Position() const;

Description

Gets the position of the mark.

Return value

TStreamPos The stream position.

void Clear();

Description

Resets the mark object to its default state.

On return from this function, the mark is uninitialised and a call to IsEmpty() returns true.

Empties the object/makes it empty so that IsEmpty() returns false

void Withdraw(TStreamExchange& aHost);

Description

Instructs the shared streaming manager to remove any reference it has to this mark object.

Parameters

TStreamExchange& aHost The object that manages shared streaming.

void ExtractL(TStreamExchange& aHost);

Description

Refreshes this mark from the mark in the host stream buffer and tells the shared streaming manager to drop any reference it has to to this mark object.

Parameters

TStreamExchange& aHost The object that manages shared streaming.

TStreamPos TellL(TStreamExchange& aHost) const;

Description

Gets the position of the mark within the host stream.

Parameters

TStreamExchange& aHost The object that manages shared streaming.

Return value

TStreamPos The stream position.

TBool operator==(const TStreamMark& aMark) const;

Description

Tests whether this object and the specified referenced shared stream mark object are the same object.

Parameters

const TStreamMark& aMark A reference to a shared stream mark object.

Return value

TBool True, if the two objects are the same object; false, otherwise.

TBool operator==(const TStreamMark* aPtr) const;

Description

Tests whether this object and the specified shared stream mark object are the same object.

Parameters

const TStreamMark* aMark A pointer to a shared stream mark object.

Return value

TBool True, if the two objects are the same object; false, otherwise.

TBool operator!=(const TStreamMark& aMark) const;

Description

Tests whether this object and the specified referenced shared stream mark object are different objects.

Parameters

const TStreamMark& aMark A reference to a shared stream mark object.

Return value

TBool True, if the two objects are different objects; false, otherwise.

TBool operator!=(const TStreamMark* aPtr) const;

Description

Tests whether this object and the specified shared stream mark object are different objects.

Parameters

const TStreamMark* aMark A pointer to a shared stream mark object.

Return value

TBool True, if the two objects are different objects; false, otherwise.

operator TStreamMark*();
operator const TStreamMark*() const;

Description

Returns this shared stream mark object.

TStreamMark& operator=(TStreamPos aPos);

Description

Assigns the specified stream position value to this shared stream mark object.

Parameters

TStreamPos aPos The stream position value to be assigned.

Return value

TStreamMark& A reference to this shared stream mark object.