CBufferedImageDecoder in Multimedia Imaging

class CBufferedImageDecoder : public CBase;

Description

Buffered image conversion library.

Provides a wrapper arround CImageDecoder that enables you to decode multiple images without having to recreate the CBufferedImageDecoder object each time. One of the key features of this class is the ability to append image data to the decoder object as it becomes available; this is done using CBufferedImageDecoder::AppendDataL(const TDesC8 &).

Derivation

CBase - Base class for all classes to be instantiated on the heap.

CBufferedImageDecoder - Buffered image conversion library.

Members

Defined in CBufferedImageDecoder:

AppendDataL(const TDesC8 &)Adds new image data.
Cancel()Requests an asynchronous decode to terminate.
ContinueConvert(TRequestStatus *)Continues decoding a frame and/or mask after new image data was added to the sou...
ContinueOpenL()Call this function to retry to create a decoder after CBufferedImageDecoder::Ope...
ContinueProcessingHeaderL()Continues processing image headers after new image data was appended.
Convert(TRequestStatus *,CFbsBitmap &,CFbsBitmap &,TInt)Starts decoding an image frame and mask asynchronously.
Convert(TRequestStatus *,CFbsBitmap &,TInt)Starts decoding an image frame asynchronously.
FrameCommentL(TInt,TInt)constReturns a particular comment attached to a given frame of the image. Ownership o...
FrameCount()constReturns the number of frames in the image being decoded. This function can be ca...
FrameData(TInt)constReturns the image data for a specific frame.
FrameInfo(TInt)constReturns the frame info for a specified frame of the image.
FrameInfoStringsL(TInt)Returns the formatted frame information strings for a specific frame.
FrameInfoStringsLC(TInt)Returns the formatted frame information strings for a specific frame and leave i...
ImageCommentL(TInt)constReturns a particular comment attached to the image. Ownership of the returned bu...
ImplementationUid()constReturns the implementation UID of the decoder being used to decode the image.
IsImageHeaderProcessingComplete()constReturns the status of the image.
NewL(RFs &)Creates a buffered decoder.
NumberOfFrameComments(TInt)constReturns the number of comments attached to a given frame of the image as opposed...
NumberOfImageComments()constReturns the number of comments attached to the image (as opposed to a particular...
Reset()Reset the decoder for reuse.
ValidDecoder()constDetermine if enough data was available to determine which plugin decoder to use....
~CBufferedImageDecoder()Destructor for this class.

Inherited from CBase:

Delete(CBase *)Deletes the specified object.
Extension_(TUint,TAny *&,TAny *)Extension function
operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TAny *)Initialises the object to binary zeroes.
operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

IMPORT_C static CBufferedImageDecoder* NewL(RFs &aFs);

Description

Creates a buffered decoder.

The function leaves if the decoder object cannot be created or initialised.

Parameters


                                 						RFs &aFs

A reference to a file server session for the decoder to use.

Return value

CBufferedImageDecoder *

A pointer to the newly created decoder.

IMPORT_C virtual ~CBufferedImageDecoder();

Description

Destructor for this class.

Stops decoding if it is in progress and frees all resources owned by the object prior to its destruction.

IMPORT_C void OpenL(const TDesC8 &aSourceData, const TDesC8 &aMIMEType, const CImageDecoder::TOptions aOptions=CImageDecoder::EOptionNone);

Description

Creates a decoder for the image in the source buffer. The client supplies a MIME type which will be used to try and select an appropriate plugin decoder. If it finds a decoder it creates it and then goes on to use that decoder to scan the beginning of the image file.

Parameters

`const TDesC8 &aSourceData`	The buffer containing the image to be decoded.
`const TDesC8 &aMIMEType`	The MIME type of the image in the buffer.
`const CImageDecoder::TOptions aOptions`	The options to use.

Leave codes

KEComErrNoInterfaceIdentified

No plugin decoder could be found for the specified image.

IMPORT_C void OpenL(const TDesC8 &aSourceData, const CImageDecoder::TOptions aOptions=CImageDecoder::EOptionNone, const TUid aImageType=TUid::Null(), const TUid aImageSubType=TUid::Null(), const TUid aDecoderUid=TUid::Null());

Description

Creates a decoder for the image in the source buffer.

If the client supplies an image type (and sub-type, if applicable) or decoder uid, these will be used to try and select an appropriate plugin decoder. If not, then the selection will be done by matching the image header from the buffer. If it finds a decoder it creates it and then goes on to use that decoder to scan the beginning of the image buffer. If a decoder could not be created append data using CBufferedImageDecoder::AppendDataL(const TDesC8 &) and call CBufferedImageDecoder::ContinueOpenL().

Parameters

`const TDesC8 &aSourceData`	The buffer containing the image to be decoded.
`const CImageDecoder::TOptions aOptions`	The decoder options to use.
`const TUid aImageType`	The image type of the image in the file (optional).
`const TUid aImageSubType`	The image sub-type of the image in the file (optional).
`const TUid aDecoderUid`	The implementation UID for a specific codec or a decoder/encoder class UID (optional, defaults to KNullUid). If this option is selected for a specific codec the image type and image sub type for the displayer must be supplied. When loading plugins by class UID the image type and image subtype are not mandatory and the first valid plugin from the list of available plugins with the specified class UID will be loaded.

Leave codes

`KErrUnderflow`	Not enough data in descriptor to identify which plugin decoder to use.
`KEComErrNoInterfaceIdentified`	No plugin decoder could be found for the specified image.
`KErrNotFound`	The specified codec could not be found.

IMPORT_C void ContinueOpenL();

Description

Call this function to retry to create a decoder after CBufferedImageDecoder::OpenL(const TDesC8 &,const TDesC8 &,const CImageDecoder::TOptions) returned with KErrUnderFlow and extra data was added to the descriptor using CBufferedImageDecoder::AppendDataL(const TDesC8 &). This function can be recalled until CBufferedImageDecoder::ValidDecoder()const return ETrue.

Leave codes

KErrUnderflow

Not enough data in descriptor to identify which plugin decoder to use.

IMPORT_C void ContinueProcessingHeaderL();

Description

Continues processing image headers after new image data was appended.

This function can be called until CBufferedImageDecoder::IsImageHeaderProcessingComplete()const return ETrue.

IMPORT_C TBool IsImageHeaderProcessingComplete() const;

Description

Returns the status of the image.

If the image is incomplete or not terminated correctly EFalse will be returned

Return value

TBool

A boolean indicating the image status. Returns ETrue if image header processing is complete, otherwise EFalse.

IMPORT_C void Convert(TRequestStatus *aRequestStatus, CFbsBitmap &aDestination, TInt aFrameNumber=0);

Description

Starts decoding an image frame asynchronously.

When converting the operation can complete with KErrUnderflow, if there is insufficient information in the descriptor. In this situation, CBufferedImageDecoder::ContinueConvert(TRequestStatus *) should be called repeatedly until the descriptor has accumulated enough information for CBufferedImageDecoder::ContinueConvert(TRequestStatus *) to complete with KErrNone.

Parameters

`TRequestStatus *aRequestStatus`	The request status. On completion contains an error code. KErrNone if frame was decoded successfully, KErrUnderflow if the frame was partially decoded otherwise another of the system-wide error codes.
`CFbsBitmap &aDestination`	A bitmap that will contain the decoded frame. The bitmap must be created before the call and must be large enough for the frame and set to the required display mode. `CBufferedImageDecoder::FrameInfo(TInt)const` can be used to obtain the size and display mode of the frame.
`TInt aFrameNumber`	The frame in multi-frame image to decode (optional).

IMPORT_C void Convert(TRequestStatus *aRequestStatus, CFbsBitmap &aDestination, CFbsBitmap &aDestinationMask, TInt aFrameNumber=0);

Description

Starts decoding an image frame and mask asynchronously.

When converting the operation can complete with KErrUnderflow, if there is insufficient information in the descriptor. In this situation, CBufferedImageDecoder::ContinueConvert(TRequestStatus *) should be called repeatedly until the descriptor has accumulated enough information for CBufferedImageDecoder::ContinueConvert(TRequestStatus *) to complete with KErrNone.

Parameters

`TRequestStatus *aRequestStatus`	The request status. On completion contains an error code. KErrNone if frame was decoded successfully, KErrUnderflow if the frame was partially decoded otherwise another of the system-wide error codes.
`CFbsBitmap &aDestination`	A bitmap that will contain the decoded frame. The bitmap must be created before the call and must be large enough for the frame and set to the required display mode. `CBufferedImageDecoder::FrameInfo(TInt)const` can be used to obtain the size and display mode of the frame.
`CFbsBitmap &aDestinationMask`	A bitmap that will contain the decoded frame mask. The bitmap must be created before the call and must be large enough for the mask. The display mode must be EGray2 or EGray256 and must be EGray256 if the image contains alpha-blending information. This information can be obtained from the iFlags property and TFrameInfoFlags of `TFrameInfo` obtained from a `CBufferedImageDecoder::FrameInfo(TInt)const` call.
`TInt aFrameNumber`	The frame in multi-frame image to decode (optional).

IMPORT_C void ContinueConvert(TRequestStatus *aRequestStatus);

Description

Continues decoding a frame and/or mask after new image data was added to the source file or descriptor and a previous call to CBufferedImageDecoder::Convert(TRequestStatus *,CFbsBitmap &,TInt) or CBufferedImageDecoder::ContinueConvert(TRequestStatus *) returned KErrUnderflow.

Parameters


                                 						TRequestStatus *aRequestStatus

The request status. On completion contains an error code. KErrNone if frame was decoded successfully, KErrUnderflow if the frame was partially decoded otherwise another of the system-wide error codes.

IMPORT_C void Cancel();

Description

Requests an asynchronous decode to terminate.

Cancels any conversions currently in progress.

IMPORT_C void Reset();

Description

Reset the decoder for reuse.

Follow this call with CBufferedImageDecoder::OpenL(const TDesC8 &,const TDesC8 &,const CImageDecoder::TOptions) and new source data.

IMPORT_C void AppendDataL(const TDesC8 &aData);

Description

Adds new image data.

A copy of the data is held internally, and the caller does not need to retain the data.

Parameters

const TDesC8 &aData

The new image data to append.

IMPORT_C TInt FrameCount() const;

Description

Returns the number of frames in the image being decoded. This function can be called immediately after the call to create the decoder, thus enabling the caller to know how many frames need to be converted.

Return value

TInt

The number of frames.

IMPORT_C const TFrameInfo& FrameInfo(TInt aFrameNumber=0) const;

Description

Returns the frame info for a specified frame of the image.

This function can be called immediately after the call to create the decoder, thus enabling the caller to know about each frame in advance of converting it.

Parameters


                                 						TInt aFrameNumber

The frame number.

Return value

const TFrameInfo &

The information for the specified frame.

IMPORT_C const CFrameImageData& FrameData(TInt aFrameNumber=0) const;

Description

Returns the image data for a specific frame.

Use CBufferedImageDecoder::FrameCount()const to determine how many frames are contained in the image before using this function.

Parameters


                                 						TInt aFrameNumber

The frame number for which to return frame data.

Return value

const CFrameImageData &

The data for the specified frame.

IMPORT_C TInt NumberOfImageComments() const;

Description

Returns the number of comments attached to the image (as opposed to a particular frame).

Return value

TInt

The number of comments attached to the image.

IMPORT_C HBufC* ImageCommentL(TInt aCommentNumber) const;

Description

Returns a particular comment attached to the image. Ownership of the returned buffer is transferred to the caller.

Use CBufferedImageDecoder::NumberOfImageComments()const to determine how many (if any) comments are contained within the image.

Parameters


                                 						TInt aCommentNumber

The comment number.

Return value

HBufC16 *

A buffer containing the comment.

IMPORT_C TInt NumberOfFrameComments(TInt aFrameNumber) const;

Description

Returns the number of comments attached to a given frame of the image as opposed to the whole image.

Use CBufferedImageDecoder::FrameCount()const to retrieve the number of frames in the image to ensure that the value you use for aFrameNumber is valid.

Parameters


                                 						TInt aFrameNumber

The frame number.

Return value

TInt

The number of comments attached to a given frame of the image.

IMPORT_C HBufC* FrameCommentL(TInt aFrameNumber, TInt aCommentNumber) const;

Description

Returns a particular comment attached to a given frame of the image. Ownership of the returned buffer is transferred to the caller.

Parameters

`TInt aFrameNumber`	The frame number.
`TInt aCommentNumber`	The comment number.

Return value

HBufC16 *

A buffer containing the comment.

IMPORT_C CFrameInfoStrings* FrameInfoStringsLC(TInt aFrameNumber=0);

Description

Returns the formatted frame information strings for a specific frame and leave it on the cleanup stack.

Ownership is transferred to the caller.

Parameters


                                 						TInt aFrameNumber

The frame number.

Return value

CFrameInfoStrings *

The formatted frame information strings.

IMPORT_C CFrameInfoStrings* FrameInfoStringsL(TInt aFrameNumber=0);

Description

Returns the formatted frame information strings for a specific frame.

Ownership is transferred to the caller.

Parameters


                                 						TInt aFrameNumber

The frame number.

Return value

CFrameInfoStrings *

The formatted frame information strings.

IMPORT_C TUid ImplementationUid() const;

Description

Returns the implementation UID of the decoder being used to decode the image.

Return value

TUid

The implementation UID of the decoder.

IMPORT_C TBool ValidDecoder() const;

Description

Determine if enough data was available to determine which plugin decoder to use. If this return EFalse append extra data using CBufferedImageDecoder::AppendDataL(const TDesC8 &) and and call CBufferedImageDecoder::ContinueOpenL()

Return value

TBool

A boolean indicating if the decoder plugin was successful. ETrue if a decoder plugin was created, otherwise EFalse.

Class CBufferedImageDecoder

Description

Derivation

Members

Construction and destruction

NewL(RFs &)

Description

Parameters

Return value