Class TStreamFilter

TStreamFilter

Support

Supported from 5.0

Description

Interface to a stream filter.

A stream filter is an object that allows stream data to be filtered after retrieval from a host or filtered before being written to a host.

The class is abstract and a derived class must be defined an implemented.

Derivation

MStreamBuf A stream buffer that provides a generic I/O interface for streamed data TStreamFilter Interface to a stream filter

Defined in TStreamFilter:
Capacity(), Committed(), DoReadL(), DoRelease(), DoSynchL(), DoWriteL(), EmitL(), FilterL(), IsCommitted(), Set(), TStreamFilter()

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

protected : TStreamFilter();

Description

Constructs an empty stream filter object.

protected : void Set(MStreamBuf* aHost,TInt aMode);

Description

Sets up the filter to use the specified host for streamed data.

Parameters

MStreamBuf* aHost The host for the streamed data - a stream buffer. TInt aMode The mode in which the stream buffer is to be used. It can be used in either read or write modes, represented by ERead and EWrite, but not both at the same time. In debug mode, setting both raises a STORE-Stream 18 panic. In addition, specify EAttached to indicate that the filter should take ownership of the host stream buffer.

Notes:

• Taking ownership of the host stream buffer means that calls to SynchL() propagate to the host buffer after the filter has flushed its data, and that when the filter is released it also releases the host buffer.

See also:

• MStreamBuf::TRead
• MStreamBuf::TWrite

protected : void Committed();
    

Description

Flags the streamed data as committed.

protected : TBool IsCommitted() const;

Description

Tests whether the streamed data is committed.

Return value

TBool True, if streamed data is committed; false, otherwise.

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

Description

Writes data from the specified memory location directly to the host without filtering.

This is useful for sending any final data, when flushing the filter as part of DoSynchL().

Parameters

constTAny* aPtr A pointer to the memory location from which data is to be written to the host stream. TInt aLength The number of bytes to be written.

Notes:

• In debug mode: the filter must be in write mode, otherwise the function raises a STORE-Stream 11 panic.
• In debug mode, a host stream must have been set before calling this function, otherwise it raises a STORE-Stream 0 panic.

See also:

• DoSynchL()

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

Description

Reads data from the host stream through the filter into the specified memory location.

Parameters

TAny* aPtr A pointer to the target memory location for the filtered data. TInt aMaxLength The maximum number of bytes to be read. In debug mode: if this value is negative then the function raises a STORE-Stream 1 panic; if this value is zero, then the function raises a STORE-Stream 3 panic.

Return value

TInt The number of bytes read.

Notes:

• In debug mode: the filter must be in read mode, otherwise the function raises a STORE-Stream 10 panic.
• In debug mode, a host stream must have been set before calling this function, otherwise it raises a STORE-Stream 0 panic.

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

Description

Writes data to the host stream through the filter from the specified memory location.

Parameters

const TAny* aPtr A pointer to the source memory location. TInt aLength The number of bytes to be written. In debug mode: if this value is negative then the function raises a STORE-Stream 1 panic; if this value is zero, then the function raises a STORE-Stream 7 panic.

Notes:

• In debug mode: the filter must be in write mode, otherwise the function raises a STORE-Stream 11 panic.
• In debug mode, a host stream must have been set before calling this function, otherwise it raises a STORE-Stream 0 panic.

protected : void DoRelease();

Description

Frees the host stream's resources.

See also:

• MStreamBuf::DoRelease()

protected : void DoSynchL();

Description

Synchronizes the host's intermediate buffer with its stream, leaving if any error occurs.

See also:

• MStreamBuf::DoSynchL()

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

Description

Calculates the maximum size of unfiltered data necessary to give the specified amount of filtered data.

Parameters

TInt aMaxLength The amount of filtered data required.

Return value

TInt The maximum amount of unfiltered data guaranteed not to generate more than aMaxLength bytes of filtered output.

private : virtual TInt FilterL(TAny* aPtr,TInt aMaxLength,const TUint8*& aFrom,const TUint8* anEnd)=0;

Description

Performs the filtration process.

Parameters

TAny* aPtr Pointer to the output location for the filtered data. TInt aMaxLength The maximum amount of space available for the filtered data. const TUint8*& aFrom A reference to a pointer to the unfiltered data source. This pointer should be advanced as the source is consumed. const TUint8* anEnd Pointer to the first byte beyond the end of the unfiltered data source.

Return value

TInt The size of the filtered data.