CImageDecoderPlugin Class Reference

#include <icl/imageplugin.h>

class CImageDecoderPlugin : public CBase

Inherits from

Public Member Functions
~CImageDecoderPlugin()
virtual IMPORT_C HBufC *FrameCommentL(TInt, TInt)
virtual IMPORT_C TIntGetDestinationSize(TSize &, TInt)
virtual IMPORT_C voidGetExtensionL(TUid, MImageConvExtension *&)
virtual IMPORT_C HBufC *ImageCommentL(TInt)
pure virtual voidImageType(TInt, TUid &, TUid &)
virtual IMPORT_C TIntNumberOfFrameComments(TInt)
virtual IMPORT_C TIntNumberOfImageComments()
virtual IMPORT_C voidSetClippingRectL(const TRect *)
Protected Member Functions
CImageDecoderPlugin()
IMPORT_C TBoolAmInThread()
IMPORT_C TIntAppendImageData(const TImageDataBlock *)
IMPORT_C TIntAppendImageDataBuffer(const HBufC8 *)
virtual IMPORT_C voidCleanup()
IMPORT_C TIntDataLength()
IMPORT_C CImageDecoder::TOptionsDecoderOptions()
IMPORT_C const CFbsBitmap &Destination()
IMPORT_C const CFbsBitmap &DestinationMask()
virtual IMPORT_C voidDoConvert()
virtual IMPORT_C TIntFrameBlockSize(TInt)
IMPORT_C const CFrameImageData &FrameData(TInt)
virtual IMPORT_C TIntFrameHeaderBlockSize(TInt)
IMPORT_C const TFrameInfo &FrameInfo(TInt)
pure virtual IMPORT_C CFrameInfoStrings *FrameInfoStringsL(RFs &, TInt)
virtual IMPORT_C voidHandleCustomSyncL(TInt)
IMPORT_C voidHandleProcessFrameResult(TInt, TFrameState)
IMPORT_C const TImageDataBlock *ImageData(TInt)
IMPORT_C TIntImageDataCount()
IMPORT_C const TFrameInfo &ImageInfo()
IMPORT_C CImageReadCodec *ImageReadCodec()
virtual IMPORT_C voidInitConvertL()
virtual IMPORT_C voidInitCustomAsyncL(TInt)
IMPORT_C TIntInsertImageData(const TImageDataBlock *, TInt)
IMPORT_C TBoolIsImageHeaderProcessingComplete()
virtual IMPORT_C voidNotifyComplete()
IMPORT_C TIntNumberOfFrames()
IMPORT_C voidOpenExtraResourceFileLC(RFs &, const TUid, RResourceFile &)
IMPORT_C TIntPosition()
IMPORT_C voidPrepareForProcessFrameL()
IMPORT_C voidReadDataL(TInt, TPtrC8 &, TInt)
virtual IMPORT_C voidReadFrameHeadersL()
IMPORT_C voidRemoveImageData(TInt)
IMPORT_C voidRequestComplete(TInt)
IMPORT_C voidRequestInitL(TInt)
pure virtual voidScanDataL()
IMPORT_C voidSelfComplete(TInt)
IMPORT_C voidSetDataLength(TInt)
IMPORT_C voidSetImageInfo(const TFrameInfo &)
IMPORT_C voidSetImageReadCodec(CImageReadCodec *)
IMPORT_C voidSetPosition(const TInt)
IMPORT_C voidSetSelfPending()
IMPORT_C voidSetStartPosition(TInt)
IMPORT_C voidSetThumbnailData(HBufC8 *)
IMPORT_C TBoolShouldAbort()
IMPORT_C TBufPtr8 &SourceData()
IMPORT_C TIntSourceLength()
IMPORT_C TIntStartPosition()
IMPORT_C TBoolValidDestination()
IMPORT_C TBoolValidDestinationMask()
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()

Detailed Description

The PluginAPI for Image Converter Library decoder plugins.

Intended for use by plugin writers only.

Constructor & Destructor Documentation

CImageDecoderPlugin ( )

IMPORT_CCImageDecoderPlugin()[protected]

Constructor for this class.

~CImageDecoderPlugin ( )

IMPORT_C~CImageDecoderPlugin()

Destructor for this class.

Member Function Documentation

AmInThread ( )

IMPORT_C TBoolAmInThread()const [protected]

Indicates if this decoder is running in a separate thread.

Return Value
ETrue if running in separate thread, otherwise EFalse

AppendImageData ( const TImageDataBlock * )

IMPORT_C TIntAppendImageData(const TImageDataBlock *aEntry)[protected]

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

Parameters
aEntryThe image data block to be appended.
Return Value
An error code indicating if the function call was successful. KErrNone on success, otherwise another of the system-wide error codes.

AppendImageDataBuffer ( const HBufC8 * )

IMPORT_C TIntAppendImageDataBuffer(const HBufC8 *aImageBuffer)[protected]

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

Parameters
aImageBufferThe data buffer to append.
Return Value
An error code indicating if the function call was successful. KErrNone on success, otherwise another of the system-wide error codes.

Cleanup ( )

IMPORT_C voidCleanup()[protected, virtual]

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.

DataLength ( )

IMPORT_C TIntDataLength()const [protected]

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

Return Value
The maximum number of bytes of data.

DecoderOptions ( )

IMPORT_C CImageDecoder::TOptionsDecoderOptions()const [protected]

Returns the decoding options specified by the client when it created the CImageDecoder object.

Return Value
The decoding options.

Destination ( )

IMPORT_C const CFbsBitmap &Destination()const [protected]

Returns the destination bitmap.

Return Value
A reference to the destination bitmap.

DestinationMask ( )

IMPORT_C const CFbsBitmap &DestinationMask()const [protected]

Returns the destination bitmap mask.

Return Value
A reference to the destination bitmap mask.

DoConvert ( )

IMPORT_C voidDoConvert()[protected, virtual]

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.

FrameBlockSize ( TInt )

IMPORT_C TIntFrameBlockSize(TIntaFrameNumber)const [protected, virtual]

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
aFrameNumberThe frame to which the block size information applies.
Return Value
The returned frame block size (always 4096).

FrameCommentL ( TInt, TInt )

IMPORT_C HBufC *FrameCommentL(TIntaFrameNumber,
TIntaCommentNumber
)const [virtual]

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

Ownership of the returned buffer is transferred to the caller.

Parameters
aFrameNumberThe index of the frame containing the comments.
aCommentNumberThe index of the comment to retrieve from the specified frame.
Return Value
A buffer containing the specified comment.

FrameData ( TInt )

IMPORT_C const CFrameImageData &FrameData(TIntaFrameNumber = 0)const [protected]

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

Parameters
aFrameNumberThe frame number from which to retreive the frame data (Optional, defaults to 0).
Return Value
The data for the specified frame.

FrameHeaderBlockSize ( TInt )

IMPORT_C TIntFrameHeaderBlockSize(TIntaFrameNumber)const [protected, virtual]

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
aFrameNumberThe frame to which the header block size information applies.
Return Value
The returned frame header block size (always 4096).

FrameInfo ( TInt )

IMPORT_C const TFrameInfo &FrameInfo(TIntaFrameNumber = 0)const [protected]

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
aFrameNumberThe frame number for which information is requested (Optional, defaults to 0).
Return Value
The information for the specified frame.

FrameInfoStringsL ( RFs &, TInt )

IMPORT_C CFrameInfoStrings *FrameInfoStringsL(RFs &aFs,
TIntaFrameNumber = 0
)[protected, pure virtual]

Returns the codec specific frame information stored in resource files.

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

Parameters
aFsA handle to a file server session.
aFrameNumberThe frame number to which the codec specific frame information applies (optional, defaults to zero).
Return Value
A pointer to a newly allocated CFrameInfoStrings object. Ownership is transferred to the caller.

GetDestinationSize ( TSize &, TInt )

IMPORT_C TIntGetDestinationSize(TSize &aSize,
TIntaFrameNumber = 0
)[virtual]

Called by framework on plugin to get the size of decoded image.

Get the size of the decoded image for the given frame. The calculation will account for any clipping rectangle set, scaling applied through the TImageConvScaler extension and any operation applied through TImageConvOperation. If TImageConvScaler::SetScalingL(.. has been called then the size of the bitmap passed to CImageDecoder::Convert must match the size returned from this function.

Gets the size of the destination CFbsBitmap needed prior to a call to Convert(). Essential when using the ICL Framework Extensions such as SetClippingRectL() or codec extensions obtained through the OperationL(), ScalerL() and BlockStreamerL() calls.

See also: CImageDecoder::OperationL() CImageDecoder::ScalerL() CImageDecoder::BlockStreamerL() CImageDecoder::SetClippingRectL() CImageDecoder::Convert()

Parameters
aSizeA reference to a TSize that specifies the size of the region that is to be decoded by a call to Convert().
aFrameNumberThe number of the frame that is to be decoded.
Return Value
KErrArgument if an error in calculation is detected e.g. if clipping rectangle is outside of the overall frame boundary. Other system wide errors.

GetExtensionL ( TUid, MImageConvExtension *& )

IMPORT_C voidGetExtensionL(TUidaExtUid,
MImageConvExtension *&aExtPtr
)[virtual]

Called by the framework to obtain a pointer to a codec implemented extension.

See also: icl_uids.hrh .

Parameters
aExtUidExtension UID normally prefixed KUidImageConv.
aExtPtrReturns a ptr to the extension implemented by the codec plugin.

HandleCustomSyncL ( TInt )

IMPORT_C voidHandleCustomSyncL(TIntaParam)[protected, virtual]

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
aParamInterpretation dependent on plugin.

HandleProcessFrameResult ( TInt, TFrameState )

IMPORT_C voidHandleProcessFrameResult(TIntaErrCode,
TFrameStateaCodecState
)[protected]

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
aErrCodeThe error result of TRAP arround ProcessFrameL().
aCodecStateThe result of ProcessFrameL() itself.

ImageCommentL ( TInt )

IMPORT_C HBufC *ImageCommentL(TIntaCommentNumber)const [virtual]

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

Parameters
aCommentNumberThe comment number.
Return Value
A buffer containing the specified comment.

ImageData ( TInt )

IMPORT_C const TImageDataBlock *ImageData(TIntaIndex)const [protected]

Returns the image data block for the specified index.

Parameters
aIndexThe index of the image data block to return.
Return Value
The image data block.

ImageDataCount ( )

IMPORT_C TIntImageDataCount()const [protected]

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

Return Value
The number of blocks.

ImageInfo ( )

IMPORT_C const TFrameInfo &ImageInfo()const [protected]

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

Return Value
Image information.

ImageReadCodec ( )

IMPORT_C CImageReadCodec *ImageReadCodec()const [protected]

Returns the plugin's read codec.

Return Value
Pointer to the plugin's read codec.

ImageType ( TInt, TUid &, TUid & )

voidImageType(TIntaFrameNumber,
TUid &aImageType,
TUid &aImageSubType
)const [pure virtual]

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

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

Parameters
aFrameNumberThe frame index for type and sub-type information should be returned.
aImageTypeOn return contains the image type UID for the specified frame.
aImageSubTypeOn return contains the image sub-type UID for the specified frame. If the sub-type does not exist KNullUid is returned.

InitConvertL ( )

IMPORT_C voidInitConvertL()[protected, virtual]

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.

InitCustomAsyncL ( TInt )

IMPORT_C voidInitCustomAsyncL(TIntaParam)[protected, virtual]

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
aParamInterpretation dependent on plugin.

InsertImageData ( const TImageDataBlock *, TInt )

IMPORT_C TIntInsertImageData(const TImageDataBlock *aEntry,
TIntaPos
)[protected]

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

Parameters
aEntryPointer to the image data block to be inserted.
aPosThe position within the arrary to insert the data block.
Return Value
KErrNone if the insertion was successful, otherwise a system wide error code.

IsImageHeaderProcessingComplete ( )

IMPORT_C TBoolIsImageHeaderProcessingComplete()const [protected]

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

Return Value
The header processing status.

NotifyComplete ( )

IMPORT_C voidNotifyComplete()[protected, virtual]

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.

NumberOfFrameComments ( TInt )

IMPORT_C TIntNumberOfFrameComments(TIntaFrameNumber)const [virtual]

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

Use NumberOfImageComments() for the image equivalent.

Parameters
aFrameNumberThe frame number.
Return Value
The number of comments attatched to a given frame of the image.

NumberOfFrames ( )

IMPORT_C TIntNumberOfFrames()const [protected]

Returns the number of frames to be decoded.

Return Value
The number of frames.

NumberOfImageComments ( )

IMPORT_C TIntNumberOfImageComments()const [virtual]

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
The number of comments attatched to the image.

OpenExtraResourceFileLC ( RFs &, const TUid, RResourceFile & )

IMPORT_C voidOpenExtraResourceFileLC(RFs &aFs,
const TUidaUid,
RResourceFile &aResourceFile
)const [protected]

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
aFsA reference to the file server.
aUidThe decoder's UID.
aResourceFileA reference to the opened resource file.

Position ( )

IMPORT_C TIntPosition()const [protected]

Returns the current position within the data.

Return Value
The current position.

PrepareForProcessFrameL ( )

IMPORT_C voidPrepareForProcessFrameL()[protected]

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

ReadDataL ( TInt, TPtrC8 &, TInt )

IMPORT_C voidReadDataL(TIntaPosition,
TPtrC8 &aReadBuffer,
TIntaLength
)[protected]

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
aPositionThe start position from where data will be read.
aReadBufferUpon completion of a successful call, points to the internal buffer containing the data read from the source.
aLengthThe size in bytes of the block of data to be read.

ReadFrameHeadersL ( )

IMPORT_C voidReadFrameHeadersL()[protected, virtual]

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

RemoveImageData ( TInt )

IMPORT_C voidRemoveImageData(TIntaPos)[protected]

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

Parameters
aPosThe index of the image data block to be removed.

RequestComplete ( TInt )

IMPORT_C voidRequestComplete(TIntaReason)[protected]

Must be called on completion of decoding the image data.

See also: CImageDecoderPlugin::SelfComplete(TInt aReason)

Parameters
aReasonKErrNone should be returned if the decoding completes successfully. If the request fails an appropriate error code should be returned.

RequestInitL ( TInt )

IMPORT_C voidRequestInitL(TIntaFrameNumber)[protected]

Forces initialization of data structures prior to decoding a frame.

Parameters
aFrameNumberThe frame in a multi-frame image to decode.

ScanDataL ( )

voidScanDataL()[protected, pure virtual]

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 function that each individual plugin must implement.

SelfComplete ( TInt )

IMPORT_C voidSelfComplete(TIntaReason)[protected]

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

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

See also: CImageDecoderPlugin::RequestComplete(TInt aReason)

Parameters
aReasonThe error code giving the reason for completion, or KErrNone if no error occurred.

SetClippingRectL ( const TRect * )

IMPORT_C voidSetClippingRectL(const TRect *aClipRect)[virtual]

Called by the framework on the plugin to apply a clipping rectangle to the image.

Sets the area of interest of the image to be decoded.

Sets the area of interest of the image to be decoded. This function can leave with any of the system-wide error codes.

See also: TRect::IsEmpty() TRect::IsNormalized() TRect::Normalize()

Parameters
aClipRectA pointer to a TRect that specifies the location and size of the region to be decoded. This rectangle must have positive width and height values as per TRect::IsNormalized() and TRect::Normalize(). Passing in a NULL value will clear the clipping rectangle.
Leave Codes
KErrNotSupportedif clipping is not supported by the codec plugin.
Othersystem-wide error codes.
KErrNotSupportedThis function is not supported.
KErrArgumentReturned if the clipping rectangle: a) is empty (i.e. IsEmpty() returns ETrue) b) is not normalised (i.e. IsNormalized() returns EFalse) c) has coordinates that are not located within, or on, the coodinates of at least one frame of the original image. d) has a width or a height of 0

SetDataLength ( TInt )

IMPORT_C voidSetDataLength(TIntaDataLength)[protected]

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

Parameters
aDataLengthThe maximum number of bytes of data.

SetImageInfo ( const TFrameInfo & )

IMPORT_C voidSetImageInfo(const TFrameInfo &aImageInfo)[protected]

Sets the image information.

Parameters
aImageInfoThe image information.

SetImageReadCodec ( CImageReadCodec * )

IMPORT_C voidSetImageReadCodec(CImageReadCodec *aImageReadCodec)[protected]

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

Parameters
aImageReadCodecPointer to the codec.

SetPosition ( const TInt )

IMPORT_C voidSetPosition(const TIntaPosition)[protected]

Sets the current position in the data.

Parameters
aPositionThe current position in the data.

SetSelfPending ( )

IMPORT_C voidSetSelfPending()[protected]

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

See also: CImageDecoderPlugin::SelfComplete(TInt aReason)

SetStartPosition ( TInt )

IMPORT_C voidSetStartPosition(TIntaDataLength)[protected]

Sets the starting position of the frame to be decoded.

Parameters
aDataLengthThe starting position in the data.

SetThumbnailData ( HBufC8 * )

IMPORT_C voidSetThumbnailData(HBufC8 *aThumbnailData)[protected]

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

Parameters
aThumbnailDataA pointer to a HBufC8 containing the thumbnail data

ShouldAbort ( )

IMPORT_C TBoolShouldAbort()const [protected]

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
ETrue if it should abort early, otherwise EFalse

SourceData ( )

IMPORT_C TBufPtr8 &SourceData()[protected]

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

SourceLength ( )

IMPORT_C TIntSourceLength()const [protected]

Returns the length of the source data in bytes.

Return Value
The length of the source data.

StartPosition ( )

IMPORT_C TIntStartPosition()const [protected]

Returns the starting position of the frame to be decoded.

Return Value
The starting position.

ValidDestination ( )

IMPORT_C TBoolValidDestination()const [protected]

Returns the validity of the destination bitmap.

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

ValidDestinationMask ( )

IMPORT_C TBoolValidDestinationMask()const [protected]

Indicates if the destination bitmap mask is valid.

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