1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/icl/imagedisplayplugin.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -0,0 +1,315 @@
1.4 +// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// 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
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// This is the plugin API for the Image Display framework
1.18 +//
1.19 +//
1.20 +
1.21 +#ifndef __IMAGEDISPLAYPLUGIN_H__
1.22 +#define __IMAGEDISPLAYPLUGIN_H__
1.23 +
1.24 +#include <imagedisplay.h>
1.25 +#include <icl/imagedisplaypluginext.h>
1.26 +
1.27 +// fwd ref
1.28 +class CImageDisplayFramework;
1.29 +class CImageDisplayPluginBody;
1.30 +
1.31 +/**
1.32 +This is the plugin API for the Image Display framework
1.33 +Intended for use by plugin writers only.
1.34 +
1.35 +@publishedAll
1.36 +@released
1.37 +*/
1.38 +class CImageDisplayPlugin : public CBase
1.39 + {
1.40 + friend class CImageDisplayFramework;
1.41 + friend class CImageDisplayPluginBody;
1.42 +
1.43 +public:
1.44 + /**
1.45 + Data source type definitions for plug-ins
1.46 + */
1.47 + enum TImageSourceType
1.48 + {
1.49 + /** Undefined. Plug-in won't be given this value */
1.50 + EImgSrcNotDefined =0,
1.51 + /** The datasource is a file name */
1.52 + EImgSrcFileName,
1.53 + /** The datasource is a file handle */
1.54 + EImgSrcFileHandle,
1.55 + /** The datasource is a descriptor */
1.56 + EImgSrcDescriptor,
1.57 + };
1.58 +
1.59 + /**
1.60 + Defines an ImageDisplay plug-in status flag values
1.61 + */
1.62 + enum TPluginStatus
1.63 + {
1.64 + /** A plug-in has nothing more to decode; also must be set also on fatal error contidition */
1.65 + EStatusNoMoreToDecode =0x00000001,
1.66 + /** The next frame is not ready yet, bitmap may contain distorted image */
1.67 + EStatusBusy =0x00000002,
1.68 + /** Image decoding is paused i.e. call Play() to continue (if EStatusNoMoreToDecode is not set) */
1.69 + EStatusPaused =0x00000004,
1.70 + /** The next frame has been already decoded*/
1.71 + EStatusFrameReady =0x00000008,
1.72 + /** May be set after image decode completion i.e. when EStatusNoMoreToDecode is set */
1.73 + EStatusDisplayThisFrameIndefinetely =0x00000010,
1.74 + /** May be set if the image format supports progressive decoding; indicates that a bitmap contains roughtly decoded image */
1.75 + EStatusPartialFrame =0x00000020,
1.76 + /** May be set in case when a plug-in asks to invalidate previous frame contents */
1.77 + EStatusEraseOutputContents =0x00000040,
1.78 + };
1.79 + /**
1.80 + Virtual destructor. Current implementation will call the REComSession::DestroyedImplementation() to finalize destruction
1.81 + of the ECom plugin
1.82 + */
1.83 + IMPORT_C ~CImageDisplayPlugin();
1.84 +
1.85 +protected:
1.86 + /**
1.87 + Initialise the plugin and check the image display settings.
1.88 +
1.89 + This is called by the ImageDisplay framework when the client app calls
1.90 + CImageDisplay::SetupL().
1.91 +
1.92 + The plugin should check the validity of the source image and all other settings
1.93 + set by the client API. If any of these is unsupported then it should leave with
1.94 + KErrArgument
1.95 +
1.96 + A plugin implementing CImageDisplayPluginExtension to allow extension of the
1.97 + client API should initialise it here.
1.98 +
1.99 + This is a virtual function that each individual plugin must implement.
1.100 +
1.101 + @leave KErrArgument
1.102 + Some of the configuration parameters are invalid
1.103 + */
1.104 + virtual void OpenL() = 0;
1.105 +
1.106 + /**
1.107 + Initiate the image display operation
1.108 +
1.109 + This is a virtual function that each individual plugin must implement.
1.110 +
1.111 + */
1.112 + virtual void Play() = 0;
1.113 +
1.114 + /**
1.115 + Pause image decoding
1.116 +
1.117 + This is a virtual function that each individual plugin must implement.
1.118 + */
1.119 + virtual void Pause() = 0;
1.120 +
1.121 + /**
1.122 + Cancel the image display operation
1.123 + May be called by the framework even when there is no outstanding request.
1.124 +
1.125 + This is a virtual function that each individual plugin must implement.
1.126 + */
1.127 + virtual void StopPlay() = 0;
1.128 +
1.129 + /**
1.130 + Should return an array of recommended image sizes i.e. sizes which would be processed faster
1.131 + @return a reference to the array of recommended image sizes
1.132 +
1.133 + This is a virtual function that each individual plugin must implement.
1.134 + */
1.135 + virtual const CImageDisplay::RImageSizeArray& RecommendedImageSizes() const=0;
1.136 +
1.137 + /**
1.138 + Exported default constructor
1.139 + */
1.140 + IMPORT_C CImageDisplayPlugin();
1.141 +
1.142 + // getters
1.143 + /**
1.144 + returns an image datasource type
1.145 + @return TImageSourceType
1.146 + */
1.147 + IMPORT_C TImageSourceType SourceType() const;
1.148 + /**
1.149 + returns an image source file name
1.150 + @return const TDesC& a reference to read-only descriptor
1.151 + @panic ImageDisplay 4 EImageWrongType if image data source is of type other than the file name
1.152 + */
1.153 + IMPORT_C const TDesC& SourceFilename() const;
1.154 + /**
1.155 + returns an image source file handle
1.156 + @return const RFile& a reference to a file handle
1.157 + @panic ImageDisplay 4 EImageWrongType if image data source is of type other than the file handle
1.158 + */
1.159 + IMPORT_C RFile& SourceFileHandle() const;
1.160 + /**
1.161 + returns an image source descriptor
1.162 + @return const TDesC8& a reference to a 8 bit descriptor
1.163 + @panic ImageDisplay 4 EImageWrongType if image data source is of type other than the descriptor
1.164 + */
1.165 + IMPORT_C const TDesC8& SourceData() const;
1.166 +
1.167 + /**
1.168 + returns an intent that is requested by client for opening the image source
1.169 + @return ContentAccess::TIntent a desired intent value
1.170 + */
1.171 + IMPORT_C ContentAccess::TIntent SourceDataIntent() const;
1.172 +
1.173 + /**
1.174 + returns requested content data Id that should be used to open content
1.175 + @return const TDesC& a desired data unique Id
1.176 + */
1.177 + IMPORT_C const TDesC& CImageDisplayPlugin::SourceDataId() const;
1.178 +
1.179 + /**
1.180 + returns an image source MIME type or KNullDesC8 if not defined
1.181 + @return const TDesC8& a reference to a 8 bit descriptor
1.182 + */
1.183 + IMPORT_C const TDesC8& SourceMimeType() const;
1.184 + /**
1.185 + returns a global image type
1.186 + @return const TUid an image type Uid
1.187 + */
1.188 + IMPORT_C const TUid SourceImageType() const;
1.189 + /**
1.190 + returns a global image subtype or KNullUid if not defined
1.191 + @return const TUid an image subtype Uid
1.192 + */
1.193 + IMPORT_C const TUid SourceImageSubType() const;
1.194 + /**
1.195 + returns a requested by an API client source clipping rect
1.196 + @param aRect a reference to source clipping rect which is valid only if return value is ETrue
1.197 + @return ETrue if clipping rect was defined by client
1.198 + */
1.199 + IMPORT_C TBool SourceRect(TRect& aRect) const;
1.200 + /**
1.201 + returns a requested by an API client destination image size
1.202 + @return const TSize - requested image size in pixels
1.203 + */
1.204 + IMPORT_C const TSize& DestinationSizeInPixels() const;
1.205 + /**
1.206 + returns a requested by an API client image options e.g. combination of the TImageOptions
1.207 + @return TUint - requested image option set
1.208 + */
1.209 + IMPORT_C TUint Options() const;
1.210 + /**
1.211 + returns ETrue if an API client requested to preserve source image aspect ratio
1.212 + @return TBool - requested aspect ratio flag
1.213 + */
1.214 + IMPORT_C TBool MaintainAspectRatio() const;
1.215 + /**
1.216 + returns a requested by an API client display mode for an image being decoded
1.217 + @return TDisplayMode - requested display mode
1.218 + */
1.219 + IMPORT_C TDisplayMode DisplayMode() const;
1.220 + /**
1.221 + A plug-in that supports an extension interface has to override this function
1.222 + @param aIFaceUid
1.223 + a request extension Uid
1.224 + @param aIFacePtr
1.225 + a reference to the pointer that should be given extension interface pointer on success
1.226 + @return KErrNotSupported if requested extension is not supported otherwise KErrNone
1.227 + */
1.228 + IMPORT_C virtual TInt ExtensionInterface(TUid aIFaceUid, TAny*& aIFacePtr);
1.229 + /**
1.230 + A plug-in that supports image mask getting has to override this function
1.231 + @param aBitmap
1.232 + a reference to bitmap pointer
1.233 + @param aMask
1.234 + a reference to bitmap pointer, a plug-in may return NULL if no mask is available
1.235 + */
1.236 + IMPORT_C virtual void GetBitmap(const CFbsBitmap*& aBitmap, const CFbsBitmap*& aMask) const;
1.237 + /**
1.238 + A plug-in that supports target bitmap status checkig has to override this function
1.239 + @return TBool - ETrue if subsequent call to the GetBitmap() able to return valid bitmaps
1.240 + */
1.241 + IMPORT_C virtual TBool ValidBitmap() const;
1.242 + /**
1.243 + A plug-in that supports source image status checking has to override this function
1.244 + @return TUint - set of the TImageStatus flags
1.245 + */
1.246 + IMPORT_C virtual TUint ImageStatus() const;
1.247 + /**
1.248 + A plug-in that supports getting of source image number of frames has to override this function
1.249 + @param aNumFrames
1.250 + Number of frames in the source image
1.251 + @return TInt - KErrNone if aNumFrames contains a valid number of frames
1.252 + */
1.253 + IMPORT_C virtual TInt NumFrames(TInt& aNumFrames) const;
1.254 +
1.255 + // callback methods - used to pass data to the clieant throught the CImageDisplayFramework
1.256 + /**
1.257 + A plug-in may use this function to determine if a previuos callback function to an API client has been completed
1.258 + @return ETrue if callback has not been completed yet
1.259 + */
1.260 + IMPORT_C TBool CallbackIsRunning() const;
1.261 + /**
1.262 + A plug-in should use this function to pass information asinchronously to an API client. This function is asinchronous.
1.263 + @param aBitmap
1.264 + a pointer to the bitmap that contains decoding result
1.265 +
1.266 + @param aStatus
1.267 + the plugin status that should be combination of the TPluginStatus set
1.268 +
1.269 + @param aUpdatedArea
1.270 + a rectangle within the aBitmap that was updated during the latest operation
1.271 +
1.272 + @param aError
1.273 + error code of latest operation
1.274 +
1.275 + */
1.276 + IMPORT_C void AsyncCallbackImageReady(const CFbsBitmap* aBitmap, TUint aStatus, const TRect& aUpdatedArea, TInt aError);
1.277 +
1.278 + /**
1.279 + A plug-in should use this function to cancel callback to a client if it is stil pending
1.280 + */
1.281 + IMPORT_C void CancelCallback();
1.282 +
1.283 +protected:
1.284 + /**
1.285 + An array containing the sizes of the images.
1.286 + */
1.287 + CImageDisplay::RImageSizeArray iImageSizes;
1.288 +
1.289 +private:
1.290 + /**
1.291 + not for public use
1.292 + */
1.293 + IMPORT_C static CImageDisplayPlugin* NewL(TUid aImplementationUid, CImageDisplayFramework& aFramework);
1.294 + void ConstructL(CImageDisplayFramework& aFramework, TUid aInstanceUid);
1.295 +
1.296 + static TInt AsyncCbGate(TAny* aPtr);
1.297 + TInt AsyncCbGate();
1.298 +
1.299 + /** Reserved. Not for public use */
1.300 + IMPORT_C virtual void ReservedVirtual1();
1.301 + /** Reserved. Not for public use */
1.302 + IMPORT_C virtual void ReservedVirtual2();
1.303 + /** Reserved. Not for public use */
1.304 + IMPORT_C virtual void ReservedVirtual3();
1.305 + /** Reserved. Not for public use */
1.306 + IMPORT_C virtual void ReservedVirtual4();
1.307 +
1.308 +private:
1.309 + CImageDisplayFramework* iFramework;
1.310 + CImageDisplayPluginBody* iBody;
1.311 + TUid iInstanceUid;
1.312 + /**
1.313 + Future proofing not for public use
1.314 + */
1.315 + TAny* iReserved1;
1.316 + };
1.317 +
1.318 +#endif // __IMAGEDISPLAYPLUGIN_H__