Class CImageDecoderPlugin

class CImageDecoderPlugin : public CBase;

Description

The PluginAPI for Image Converter Library decoder plugins.

Intended for use by plugin writers only.

Derivation

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

• CImageDecoderPlugin - The PluginAPI for Image Converter Library decoder plugins

Members

Defined in CImageDecoderPlugin:
AmInThread(), AppendImageData(), AppendImageDataBuffer(), CImageDecoderPlugin(), Cleanup(), DataLength(), Destination(), DestinationMask(), DoConvert(), FrameBlockSize(), FrameCommentL(), FrameData(), FrameHeaderBlockSize(), FrameInfo(), FrameInfoStringsL(), HandleCustomSyncL(), HandleProcessFrameResult(), ImageCommentL(), ImageData(), ImageDataCount(), ImageInfo(), ImageReadCodec(), ImageType(), InitConvertL(), InitCustomAsyncL(), InsertImageData(), IsImageHeaderProcessingComplete(), NotifyComplete(), NumberOfFrameComments(), NumberOfFrames(), NumberOfImageComments(), OpenExtraResourceFileLC(), Position(), PrepareForProcessFrameL(), ReadDataL(), ReadFrameHeadersL(), RemoveImageData(), RequestComplete(), RequestInitL(), ScanDataL(), SelfComplete(), SetDataLength(), SetImageInfo(), SetImageReadCodec(), SetPosition(), SetSelfPending(), SetStartPosition(), SetThumbnailData(), ShouldAbort(), SourceData(), SourceLength(), StartPosition(), ValidDestination(), ValidDestinationMask(), ~CImageDecoderPlugin()

Inherited from CBase:
Delete(), Extension_(), operator new()

IMPORT_C ~CImageDecoderPlugin();

Description

Destructor for this class.

protected: IMPORT_C CImageDecoderPlugin();

Description

Constructor for this class.

virtual IMPORT_C TInt NumberOfImageComments() const;

Description

Returns the number of comments attatched to the image.

Some image formats allow comments to be attached to the entire image, others allow comments to be attached to individual frames within the image. Use this function to retrieve the number of comments in the image. Use NumberOfFrameComments() for the frame equivalent.

Return value

TInt The number of comments attatched to the image.

virtual IMPORT_C HBufC *ImageCommentL(TInt aCommentNumber) const;

Description

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

Parameters

TInt aCommentNumber The comment number.

Return value

HBufC * A buffer containing the specified comment.

virtual IMPORT_C TInt NumberOfFrameComments(TInt aFrameNumber) const;

Description

Returns the number of comments attatched to a given frame of the image.

Use NumberOfImageComments() for the image equivalent.

Parameters

TInt aFrameNumber The frame number.

Return value

TInt The number of comments attatched to a given frame of the image.

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

Description

Returns a particular comment attatched to a given frame of the image.

Ownership of the returned buffer is transferred to the caller.

Parameters

TInt aFrameNumber The index of the frame containing the comments. TInt aCommentNumber The index of the comment to retrieve from the specified frame.

Return value

HBufC * A buffer containing the specified comment.

virtual void ImageType(TInt aFrameNumber, TUid &aImageType, TUid &aImageSubType) const=0;

Description

Returns the image type and sub-type for a given frame of the image that has just been opened.

This is a virtual funtion that each individual plugin must implement.

Parameters

TInt aFrameNumber The frame index for type and sub-type information should be returned. TUid &aImageType On return contains the image type UID for the specified frame. TUid &aImageSubType On return contains the image sub-type UID for the specified frame. If the sub-type does not exist KNullUid is returned.

protected: virtual IMPORT_C void Cleanup();

Description

Called when the plugin is destroyed or a decode is cancelled. This may be overriden in derived classes.

Note: Derived classes must call this version after performing any plugin specific cleanup.

protected: virtual IMPORT_C void ReadFrameHeadersL();

Description

Invokes the ReadFrameHeadersL method of the supplied plugin which should process the frame headers contained within the image.

protected: virtual void ScanDataL()=0;

Description

Invokes the ReadFrameHeadersL() method of the supplied plugin.

The plugin's version of ReadFrameHeadersL() should read the image header information, create the required codec and read the frame headers.

This is a virtual funtion that each individual plugin must implement.

protected: virtual IMPORT_C TInt FrameHeaderBlockSize(TInt aFrameNumber) const;

Description

Returns the block size used in the specified frame's header. Always returns 4096 regardless of the frame number specified. Should be overriden by codecs that use larger blocks.

Parameters

TInt aFrameNumber The frame to which the header block size information applies.

Return value

TInt The returned frame header block size (always 4096).

protected: virtual IMPORT_C TInt FrameBlockSize(TInt aFrameNumber) const;

Description

Returns the block size used in the specified frame. Always returns 4096 regardless of the frame number specified. Should be overriden by codecs that use larger blocks.

Parameters

TInt aFrameNumber The frame to which the block size information applies.

Return value

TInt The returned frame block size (always 4096).

protected: virtual IMPORT_C CFrameInfoStrings *FrameInfoStringsL(RFs &aFs, TInt aFrameNumber=0)=0;

Description

Returns the codec specific frame information stored in resource files.

This is a virtual funtion that each individual plugin must implement.

Parameters

RFs &aFs A handle to a file server session. TInt aFrameNumber The frame number to which the codec specific frame information applies (optional, defaults to zero).

Return value

CFrameInfoStrings * A pointer to a newly allocated CFrameInfoStrings object. Ownership is transferred to the caller.

protected: IMPORT_C void OpenExtraResourceFileLC(RFs &aFs, const TUid aUid, RResourceFile &aResourceFile) const;

Description

Locates the extra resource file for the decoder aUid_extra.rsc, opens the resource file and pushes it on the cleanup stack.

If the resource file is not found the method leaves with KErrNotFound. If more than one resource file is found, only the first one is opened.

Parameters

RFs &aFs A reference to the file server. const TUid aUid The decoder's UID. RResourceFile &aResourceFile A reference to the opened resource file.

protected: IMPORT_C void ReadDataL(TInt aPosition, TPtrC8 &aReadBuffer, TInt aLength);

Description

Reads a block of data into an internal buffer.

A block of data of size aLength is read from the position specified by aPosition to an internal data buffer. After a successful read, aReadBuffer is set to point to the internal buffer.

If an attempt is made to read past the end of data, all available data is read and the descriptors length will indicate the actual number of bytes read.

Parameters

TInt aPosition The start position from where data will be read. TPtrC8 &aReadBuffer Upon completion of a successful call, points to the internal buffer containing the data read from the source. TInt aLength The size in bytes of the block of data to be read.

protected: virtual IMPORT_C void InitConvertL();

Description

Initialises data structures prior to decoding a frame.

This function may be overriden in derived classes. Any override should also call this version after performing any plugin initialistion.

protected: IMPORT_C void RequestInitL(TInt aFrameNumber);

Description

Forces initialization of data structures prior to decoding a frame.

Parameters

TInt aFrameNumber The frame in a multi-frame image to decode.

protected: virtual IMPORT_C void DoConvert();

Description

Performs a decode step. This effectively forms the RunL() call of the decoder.

This call may be overriden in derived classes. However, if this the case, then if the custom decode is not performed and the derived class should either ensure that this base class's version is called or should completely replace the base class's version calling PrepareForProcessFrameL(), ProcessFrameL() and HandleProcessFrameResult() as appropriate. Unlike the standard version, an override instance may choose to spread these calls over several RunL() instances.

protected: IMPORT_C void PrepareForProcessFrameL();

Description

Initialises system for ProcessFrameL(). This reads in a new buffer for ProcessFrameL().

protected: IMPORT_C void HandleProcessFrameResult(TInt aErrCode, TFrameState aCodecState);

Description

Deals with result from ProcessFrameL(). This function processes the results of the standard ProcessFrameL() call, feeding in the resultant error code from its TRAP and the status result. It will call RequestComplete() or SelfComplete() as appropriate.

Note that if no data was consumed by ProcessFrameL(), HandleProcessFrameResult() assumes that it requires more data and calls RequestComplete(KErrUnderflow). If this is not appropriate, an overloaded DoConvert() should be made to handle it.

Parameters

TInt aErrCode The error result of TRAP arround ProcessFrameL(). TFrameState aCodecState The result of ProcessFrameL() itself.

protected: IMPORT_C TBufPtr8 &SourceData();

Description

Value to be fed to CImageReadCodec::ProcessFrameL().

This value is setup by PrepareForProcessFrameL() - it returns the value that will be fed to CImageReadCodec::ProcessFrameL(), and will be used by codecs that fully override DoConvert().

Return value

TBufPtr8 &

protected: IMPORT_C void RequestComplete(TInt aReason);

Description

Must be called on completion of decoding the image data.

Parameters

TInt aReason KErrNone should be returned if the decoding completes successfully. If the request fails an appropriate error code should be returned.

protected: IMPORT_C void SelfComplete(TInt aReason);

Description

Must be called at the end of a slice of decoding.

If successful specify KErrNone that results in a repeat call to DoConvert().

Parameters

TInt aReason The error code giving the reason for completion, or KErrNone if no error occurred.

protected: IMPORT_C void SetSelfPending();

Description

May be called at the start of a slice of decoding if the decoding is expected to complete asynchronously. This sets the AO in CImageDecoderPriv to active, but does not complete the request.

When decoding of the slice is complete, there must be a call to SelfComplete().

protected: IMPORT_C TBool IsImageHeaderProcessingComplete() const;

Description

Returns the status of header processing. If the processing is incomplete or not terminated correctly EFalse will be returned

Return value

TBool The header processing status.

protected: IMPORT_C CImageReadCodec *ImageReadCodec() const;

Description

Returns the plugin's read codec.

Return value

CImageReadCodec * Pointer to the plugin's read codec.

protected: IMPORT_C void SetImageReadCodec(CImageReadCodec *aImageReadCodec);

Description

Sets the plugin's read codec. Ownership of the codec is transferred to the plugin.

Parameters

CImageReadCodec *aImageReadCodec Pointer to the codec.

protected: IMPORT_C const TFrameInfo &ImageInfo() const;

Description

Returns image information such as colour depth, scaling support etc.

Return value

const TFrameInfo & Image information.

protected: IMPORT_C void SetImageInfo(const TFrameInfo &aImageInfo);

Description

Sets the image information.

Parameters

const TFrameInfo &aImageInfo The image information.

protected: IMPORT_C TInt NumberOfFrames() const;

Description

Returns the number of frames to be decoded.

Return value

TInt The number of frames.

protected: IMPORT_C const TImageDataBlock *ImageData(TInt aIndex) const;

Description

Returns the image data block for the specified index.

Parameters

TInt aIndex The index of the image data block to return.

Return value

const TImageDataBlock * The image data block.

protected: IMPORT_C TInt InsertImageData(const TImageDataBlock *aEntry, TInt aPos);

Description

Inserts an image data block into the internally held array at the specified position.

Parameters

const TImageDataBlock *aEntry Pointer to the image data block to be inserted. TInt aPos The position within the arrary to insert the data block.

Return value

TInt KErrNone if the insertion was successful, otherwise a system wide error code.

protected: IMPORT_C TInt AppendImageData(const TImageDataBlock *aEntry);

Description

Appends a new image data data block to the end of the internally held array.

Parameters

const TImageDataBlock *aEntry The image data block to be appended.

Return value

TInt An error code indicating if the function call was successful. KErrNone on success, otherwise another of the system-wide error codes.

protected: IMPORT_C void RemoveImageData(TInt aPos);

Description

Removes a specified image data block from the internally held array.

Parameters

TInt aPos The index of the image data block to be removed.

protected: IMPORT_C TInt ImageDataCount() const;

Description

Returns the number of image data blocks present in the image data.

Return value

TInt The number of blocks.

protected: IMPORT_C TInt AppendImageDataBuffer(const HBufC8 *aImageBuffer);

Description

Appends a new image data buffer to the end of the internally held array

Parameters

const HBufC8 *aImageBuffer The data buffer to append.

Return value

TInt An error code indicating if the function call was successful. KErrNone on success, otherwise another of the system-wide error codes.

protected: IMPORT_C TInt DataLength() const;

Description

Returns the maximum number of bytes of data that can be decoded.

Return value

TInt The maximum number of bytes of data.

protected: IMPORT_C void SetDataLength(TInt aDataLength);

Description

Sets the maximum number of bytes of data that can be decoded.

Parameters

TInt aDataLength The maximum number of bytes of data.

protected: IMPORT_C TInt Position() const;

Description

Returns the current position within the data.

Return value

TInt The current position.

protected: IMPORT_C void SetPosition(const TInt aPosition);

Description

Sets the current position in the data.

Parameters

const TInt aPosition The current position in the data.

protected: IMPORT_C TInt StartPosition() const;

Description

Returns the starting position of the frame to be decoded.

Return value

TInt The starting position.

protected: IMPORT_C void SetStartPosition(TInt aDataLength);

Description

Sets the starting position of the frame to be decoded.

Parameters

TInt aDataLength The starting position in the data.

protected: IMPORT_C const CFbsBitmap &Destination() const;

Description

Returns the destination bitmap.

Return value

const CFbsBitmap & A reference to the destination bitmap.

protected: IMPORT_C TBool ValidDestination() const;

Description

Returns the validity of the destination bitmap.

Return value

TBool A boolean indicating if the destination bitmap is valid. ETrue if the destination bitmap is valid, EFalse otherwise.

protected: IMPORT_C const CFbsBitmap &DestinationMask() const;

Description

Returns the destination bitmap mask.

Return value

const CFbsBitmap & A reference to the destination bitmap mask.

protected: IMPORT_C TBool ValidDestinationMask() const;

Description

Indicates if the destination bitmap mask is valid.

Return value

TBool A boolean indicating if the destination bitmap is valid. ETrue if the destination bitmap mask is valid, otherwise EFalse.

protected: 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 decoding it.

Parameters

TInt aFrameNumber The frame number for which information is requested (Optional, defaults to 0).

Return value

const TFrameInfo & The information for the specified frame.

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

Description

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

Parameters

TInt aFrameNumber The frame number from which to retreive the frame data (Optional, defaults to 0).

Return value

const CFrameImageData & The data for the specified frame.

protected: IMPORT_C TInt SourceLength() const;

Description

Returns the length of the source data in bytes.

Return value

TInt The length of the source data.

protected: virtual IMPORT_C void HandleCustomSyncL(TInt aParam);

Description

Called as a result of an associated CImageDecoder::CustomSyncL() function being called. Plugins may override this to provide extended commands in CImageDecoder. Default version leaves with KErrNotSupported.

Parameters

TInt aParam Interpretation dependent on plugin.

protected: virtual IMPORT_C void InitCustomAsyncL(TInt aParam);

Description

Called as a result of the associated CImageDecoder::CustomAsync() function being called.

If this function finishes normally, then a convert cycle is started - so that DoConvert() will be subsequently started in the background - otherwise, if this function leaves then the error result is immediately signalled back to the caller of CustomAsync().

Plugins may override this to provide extended commands in CImageDecoder.Users of CImageEncoder can then use the extended encoder functions by calling CustomAsync, rather than CImageEncoder::Convert().

By default this function leaves with KErrNotSupported unless overriden.

Parameters

TInt aParam Interpretation dependent on plugin.

protected: virtual IMPORT_C void NotifyComplete();

Description

Plugin defined actions resulting from a call by RequestComplete().

This function is called when a RequestComplete() is issued indicating that an asynchronous command has finished. Plugins can extend this function to, clear any custom command flags.

protected: IMPORT_C TBool AmInThread() const;

Description

Indicates if this decoder is running in a separate thread.

Return value

TBool ETrue if running in separate thread, otherwise EFalse

protected: IMPORT_C TBool ShouldAbort() const;

Description

Indicates if the decoder should abort early ie. following a call to Cancel().

Note: This function always returns false unless the decoder is running in its own thread.

Return value

TBool ETrue if it should abort early, otherwise EFalse

protected: IMPORT_C void SetThumbnailData(HBufC8 *aThumbnailData);

Description

Passes a pointer to a descriptor containing the thumbnail from the plugin to the framework. The framework then owns this descriptor.

Parameters

HBufC8 *aThumbnailData A pointer to a HBufC8 containing the thumbnail data