williamr@2: // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: // All rights reserved. williamr@2: // This component and the accompanying materials are made available williamr@2: // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members williamr@2: // which accompanies this distribution, and is available williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". williamr@2: // williamr@2: // Initial Contributors: williamr@2: // Nokia Corporation - initial contribution. williamr@2: // williamr@2: // Contributors: williamr@2: // williamr@2: // Description: williamr@2: // This is the plugin API for the Image Display framework williamr@2: // williamr@2: // williamr@2: williamr@2: #ifndef __IMAGEDISPLAYPLUGIN_H__ williamr@2: #define __IMAGEDISPLAYPLUGIN_H__ williamr@2: williamr@2: #include williamr@2: #include williamr@2: williamr@2: // fwd ref williamr@2: class CImageDisplayFramework; williamr@2: class CImageDisplayPluginBody; williamr@2: williamr@2: /** williamr@2: This is the plugin API for the Image Display framework williamr@2: Intended for use by plugin writers only. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class CImageDisplayPlugin : public CBase williamr@2: { williamr@2: friend class CImageDisplayFramework; williamr@2: friend class CImageDisplayPluginBody; williamr@2: williamr@2: public: williamr@2: /** williamr@2: Data source type definitions for plug-ins williamr@2: */ williamr@2: enum TImageSourceType williamr@2: { williamr@2: /** Undefined. Plug-in won't be given this value */ williamr@2: EImgSrcNotDefined =0, williamr@2: /** The datasource is a file name */ williamr@2: EImgSrcFileName, williamr@2: /** The datasource is a file handle */ williamr@2: EImgSrcFileHandle, williamr@2: /** The datasource is a descriptor */ williamr@2: EImgSrcDescriptor, williamr@2: }; williamr@2: williamr@2: /** williamr@2: Defines an ImageDisplay plug-in status flag values williamr@2: */ williamr@2: enum TPluginStatus williamr@2: { williamr@2: /** A plug-in has nothing more to decode; also must be set also on fatal error contidition */ williamr@2: EStatusNoMoreToDecode =0x00000001, williamr@2: /** The next frame is not ready yet, bitmap may contain distorted image */ williamr@2: EStatusBusy =0x00000002, williamr@2: /** Image decoding is paused i.e. call Play() to continue (if EStatusNoMoreToDecode is not set) */ williamr@2: EStatusPaused =0x00000004, williamr@2: /** The next frame has been already decoded*/ williamr@2: EStatusFrameReady =0x00000008, williamr@2: /** May be set after image decode completion i.e. when EStatusNoMoreToDecode is set */ williamr@2: EStatusDisplayThisFrameIndefinetely =0x00000010, williamr@2: /** May be set if the image format supports progressive decoding; indicates that a bitmap contains roughtly decoded image */ williamr@2: EStatusPartialFrame =0x00000020, williamr@2: /** May be set in case when a plug-in asks to invalidate previous frame contents */ williamr@2: EStatusEraseOutputContents =0x00000040, williamr@2: }; williamr@2: /** williamr@2: Virtual destructor. Current implementation will call the REComSession::DestroyedImplementation() to finalize destruction williamr@2: of the ECom plugin williamr@2: */ williamr@2: IMPORT_C ~CImageDisplayPlugin(); williamr@2: williamr@2: protected: williamr@2: /** williamr@2: Initialise the plugin and check the image display settings. williamr@2: williamr@2: This is called by the ImageDisplay framework when the client app calls williamr@2: CImageDisplay::SetupL(). williamr@2: williamr@2: The plugin should check the validity of the source image and all other settings williamr@2: set by the client API. If any of these is unsupported then it should leave with williamr@2: KErrArgument williamr@2: williamr@2: A plugin implementing CImageDisplayPluginExtension to allow extension of the williamr@2: client API should initialise it here. williamr@2: williamr@2: This is a virtual function that each individual plugin must implement. williamr@2: williamr@2: @leave KErrArgument williamr@2: Some of the configuration parameters are invalid williamr@2: */ williamr@2: virtual void OpenL() = 0; williamr@2: williamr@2: /** williamr@2: Initiate the image display operation williamr@2: williamr@2: This is a virtual function that each individual plugin must implement. williamr@2: williamr@2: */ williamr@2: virtual void Play() = 0; williamr@2: williamr@2: /** williamr@2: Pause image decoding williamr@2: williamr@2: This is a virtual function that each individual plugin must implement. williamr@2: */ williamr@2: virtual void Pause() = 0; williamr@2: williamr@2: /** williamr@2: Cancel the image display operation williamr@2: May be called by the framework even when there is no outstanding request. williamr@2: williamr@2: This is a virtual function that each individual plugin must implement. williamr@2: */ williamr@2: virtual void StopPlay() = 0; williamr@2: williamr@2: /** williamr@2: Should return an array of recommended image sizes i.e. sizes which would be processed faster williamr@2: @return a reference to the array of recommended image sizes williamr@2: williamr@2: This is a virtual function that each individual plugin must implement. williamr@2: */ williamr@2: virtual const CImageDisplay::RImageSizeArray& RecommendedImageSizes() const=0; williamr@2: williamr@2: /** williamr@2: Exported default constructor williamr@2: */ williamr@2: IMPORT_C CImageDisplayPlugin(); williamr@2: williamr@2: // getters williamr@2: /** williamr@2: returns an image datasource type williamr@2: @return TImageSourceType williamr@2: */ williamr@2: IMPORT_C TImageSourceType SourceType() const; williamr@2: /** williamr@2: returns an image source file name williamr@2: @return const TDesC& a reference to read-only descriptor williamr@2: @panic ImageDisplay 4 EImageWrongType if image data source is of type other than the file name williamr@2: */ williamr@2: IMPORT_C const TDesC& SourceFilename() const; williamr@2: /** williamr@2: returns an image source file handle williamr@2: @return const RFile& a reference to a file handle williamr@2: @panic ImageDisplay 4 EImageWrongType if image data source is of type other than the file handle williamr@2: */ williamr@2: IMPORT_C RFile& SourceFileHandle() const; williamr@2: /** williamr@2: returns an image source descriptor williamr@2: @return const TDesC8& a reference to a 8 bit descriptor williamr@2: @panic ImageDisplay 4 EImageWrongType if image data source is of type other than the descriptor williamr@2: */ williamr@2: IMPORT_C const TDesC8& SourceData() const; williamr@2: williamr@2: /** williamr@2: returns an intent that is requested by client for opening the image source williamr@2: @return ContentAccess::TIntent a desired intent value williamr@2: */ williamr@2: IMPORT_C ContentAccess::TIntent SourceDataIntent() const; williamr@2: williamr@2: /** williamr@2: returns requested content data Id that should be used to open content williamr@2: @return const TDesC& a desired data unique Id williamr@2: */ williamr@2: IMPORT_C const TDesC& CImageDisplayPlugin::SourceDataId() const; williamr@2: williamr@2: /** williamr@2: returns an image source MIME type or KNullDesC8 if not defined williamr@2: @return const TDesC8& a reference to a 8 bit descriptor williamr@2: */ williamr@2: IMPORT_C const TDesC8& SourceMimeType() const; williamr@2: /** williamr@2: returns a global image type williamr@2: @return const TUid an image type Uid williamr@2: */ williamr@2: IMPORT_C const TUid SourceImageType() const; williamr@2: /** williamr@2: returns a global image subtype or KNullUid if not defined williamr@2: @return const TUid an image subtype Uid williamr@2: */ williamr@2: IMPORT_C const TUid SourceImageSubType() const; williamr@2: /** williamr@2: returns a requested by an API client source clipping rect williamr@2: @param aRect a reference to source clipping rect which is valid only if return value is ETrue williamr@2: @return ETrue if clipping rect was defined by client williamr@2: */ williamr@2: IMPORT_C TBool SourceRect(TRect& aRect) const; williamr@2: /** williamr@2: returns a requested by an API client destination image size williamr@2: @return const TSize - requested image size in pixels williamr@2: */ williamr@2: IMPORT_C const TSize& DestinationSizeInPixels() const; williamr@2: /** williamr@2: returns a requested by an API client image options e.g. combination of the TImageOptions williamr@2: @return TUint - requested image option set williamr@2: */ williamr@2: IMPORT_C TUint Options() const; williamr@2: /** williamr@2: returns ETrue if an API client requested to preserve source image aspect ratio williamr@2: @return TBool - requested aspect ratio flag williamr@2: */ williamr@2: IMPORT_C TBool MaintainAspectRatio() const; williamr@2: /** williamr@2: returns a requested by an API client display mode for an image being decoded williamr@2: @return TDisplayMode - requested display mode williamr@2: */ williamr@2: IMPORT_C TDisplayMode DisplayMode() const; williamr@2: /** williamr@2: A plug-in that supports an extension interface has to override this function williamr@2: @param aIFaceUid williamr@2: a request extension Uid williamr@2: @param aIFacePtr williamr@2: a reference to the pointer that should be given extension interface pointer on success williamr@2: @return KErrNotSupported if requested extension is not supported otherwise KErrNone williamr@2: */ williamr@2: IMPORT_C virtual TInt ExtensionInterface(TUid aIFaceUid, TAny*& aIFacePtr); williamr@2: /** williamr@2: A plug-in that supports image mask getting has to override this function williamr@2: @param aBitmap williamr@2: a reference to bitmap pointer williamr@2: @param aMask williamr@2: a reference to bitmap pointer, a plug-in may return NULL if no mask is available williamr@2: */ williamr@2: IMPORT_C virtual void GetBitmap(const CFbsBitmap*& aBitmap, const CFbsBitmap*& aMask) const; williamr@2: /** williamr@2: A plug-in that supports target bitmap status checkig has to override this function williamr@2: @return TBool - ETrue if subsequent call to the GetBitmap() able to return valid bitmaps williamr@2: */ williamr@2: IMPORT_C virtual TBool ValidBitmap() const; williamr@2: /** williamr@2: A plug-in that supports source image status checking has to override this function williamr@2: @return TUint - set of the TImageStatus flags williamr@2: */ williamr@2: IMPORT_C virtual TUint ImageStatus() const; williamr@2: /** williamr@2: A plug-in that supports getting of source image number of frames has to override this function williamr@2: @param aNumFrames williamr@2: Number of frames in the source image williamr@2: @return TInt - KErrNone if aNumFrames contains a valid number of frames williamr@2: */ williamr@2: IMPORT_C virtual TInt NumFrames(TInt& aNumFrames) const; williamr@2: williamr@2: // callback methods - used to pass data to the clieant throught the CImageDisplayFramework williamr@2: /** williamr@2: A plug-in may use this function to determine if a previuos callback function to an API client has been completed williamr@2: @return ETrue if callback has not been completed yet williamr@2: */ williamr@2: IMPORT_C TBool CallbackIsRunning() const; williamr@2: /** williamr@2: A plug-in should use this function to pass information asinchronously to an API client. This function is asinchronous. williamr@2: @param aBitmap williamr@2: a pointer to the bitmap that contains decoding result williamr@2: williamr@2: @param aStatus williamr@2: the plugin status that should be combination of the TPluginStatus set williamr@2: williamr@2: @param aUpdatedArea williamr@2: a rectangle within the aBitmap that was updated during the latest operation williamr@2: williamr@2: @param aError williamr@2: error code of latest operation williamr@2: williamr@2: */ williamr@2: IMPORT_C void AsyncCallbackImageReady(const CFbsBitmap* aBitmap, TUint aStatus, const TRect& aUpdatedArea, TInt aError); williamr@2: williamr@2: /** williamr@2: A plug-in should use this function to cancel callback to a client if it is stil pending williamr@2: */ williamr@2: IMPORT_C void CancelCallback(); williamr@2: williamr@2: protected: williamr@2: /** williamr@2: An array containing the sizes of the images. williamr@2: */ williamr@2: CImageDisplay::RImageSizeArray iImageSizes; williamr@2: williamr@2: private: williamr@2: /** williamr@2: not for public use williamr@2: */ williamr@2: IMPORT_C static CImageDisplayPlugin* NewL(TUid aImplementationUid, CImageDisplayFramework& aFramework); williamr@2: void ConstructL(CImageDisplayFramework& aFramework, TUid aInstanceUid); williamr@2: williamr@2: static TInt AsyncCbGate(TAny* aPtr); williamr@2: TInt AsyncCbGate(); williamr@2: williamr@2: /** Reserved. Not for public use */ williamr@2: IMPORT_C virtual void ReservedVirtual1(); williamr@2: /** Reserved. Not for public use */ williamr@2: IMPORT_C virtual void ReservedVirtual2(); williamr@2: /** Reserved. Not for public use */ williamr@2: IMPORT_C virtual void ReservedVirtual3(); williamr@2: /** Reserved. Not for public use */ williamr@2: IMPORT_C virtual void ReservedVirtual4(); williamr@2: williamr@2: private: williamr@2: CImageDisplayFramework* iFramework; williamr@2: CImageDisplayPluginBody* iBody; williamr@2: TUid iInstanceUid; williamr@2: /** williamr@2: Future proofing not for public use williamr@2: */ williamr@2: TAny* iReserved1; williamr@2: }; williamr@2: williamr@2: #endif // __IMAGEDISPLAYPLUGIN_H__