--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/imagehandling_plat/thumbnailmanager_api/inc/thumbnailmanager.h Tue Jan 26 15:18:05 2010 +0200
@@ -0,0 +1,554 @@
+/*
+* Copyright (c) 2006-2007 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Main interface class to Thumbnail Manager
+ *
+*/
+
+
+#ifndef THUMBNAILMANAGER_H
+#define THUMBNAILMANAGER_H
+
+#include <e32base.h>
+#include <gdi.h>
+#include <badesca.h>
+
+#include <thumbnailobjectsource.h>
+
+class MThumbnailManagerObserver;
+
+typedef TInt TThumbnailRequestId;
+
+typedef TUint32 TThumbnailId;
+typedef enum
+{
+EUnknownThumbnailSize,
+ECustomThumbnailSize,
+EImageGridThumbnailSize,
+EImageListThumbnailSize,
+EImageFullScreenThumbnailSize,
+EVideoGridThumbnailSize,
+EVideoListThumbnailSize,
+EVideoFullScreenThumbnailSize,
+EAudioGridThumbnailSize,
+EAudioListThumbnailSize,
+EAudioFullScreenThumbnailSize,
+EGridThumbnailSize,
+EListThumbnailSize,
+EFullScreenThumbnailSize
+} TThumbnailSize;
+/**
+ * Thumbnail engine.
+ *
+ * This is the main interface class to thumbnail engine. Thumbnail engine
+ * can be used to request thumbnails for different kinds of media objects.
+ *
+ * The client using thumbnail engine must implement the
+ * MThumbnailManagerObserver. The observer interface is used to provide
+ * thumbnail data when it is available.
+ *
+ * Typical use of thumbnail engine consists of 4 parts:
+ * - creating an engine instance using NewL
+ * - setting thumbnail parameters using SetThumbnailSizeL(), SetFlags(),
+ * and so on
+ * - creating an object source (CThumbnailObjectSource) and using it to
+ * request thumbnails
+ * - handling MThumbnailManagerObserver callbacks when the thumbnail request
+ * is complete
+ *
+ * Here is an example of how thumbnail engine could be used by a typical
+ * application:
+ *
+ * @code
+ *
+ * #include <thumbnailmanagerobserver.h>
+ * #include <thumbnailmanager.h>
+ *
+ * class CMyThumbnailControl: public CCoeControl,
+ * public MThumbnailManagerObserver
+ * {
+ * public:
+ * CMyThumbnailControl();
+ * ~CMyThumbnailControl();
+ * ...
+ *
+ * // Callbacks from MThumbnailManagerObserver for getting thumbnails
+ * void ThumbnailPreviewReady(
+ * MThumbnailData& aThumbnail,
+ * TThumbnailRequestId aId );
+ * void ThumbnailReady(
+ * TInt aError,
+ * MThumbnailData& aThumbnail,
+ * TThumbnailRequestId aId );
+ *
+ * private:
+ * void ConstructL();
+ * CThumbnailManager* iManager;
+ * CFbsBitmap* iBitmap;
+ * }
+ *
+ * _LIT( KTestFilePath, "e:\\TestImage.jpg" );
+ * _LIT( KTestFileType, "image/jpeg" );
+ *
+ * void CMyThumbnailControl::ConstructL()
+ * {
+ * // Create Thumbnail Manager instance. This object is the observer.
+ * iManager = CThumbnailManager::NewL( *this );
+ *
+ * // Set flags: If the aspect ratio of the media object does not match
+ * // 4:3 then we would like it to be cropped. We don’t mind getting
+ * // smaller images than requested.
+ * iManager->SetFlagsL( CThumbnailManager::ECropToAspectRatio |
+ * CThumbnailManager::EAllowAnySize );
+ *
+ * // Preferred size is 160x120 (or less)
+ * iManager->SetSizeL( TSize( 160, 120 ) );
+ *
+ * // Get a preview thumbnail first, if available.
+ * // The preview thumbnail is delivered via a ThumbnailPreviewReady()
+ * // callback.
+ * iManager->SetQualityPreferenceL(
+ * CThumbnailManager::EOptimizeForQualityWithPreview );
+ *
+ * // Create an object source representing a path to a file on local
+ * // file system.
+ * CThumbnailObjectSource* source = CThumbnailObjectSource::NewLC(
+ * KTestFilePath, // File path
+ * KTestFileType ); // Let Thumbnail Manager know it’s a JPEG, so
+ * // it doesn’t need to recognize the file format
+ *
+ * // Issue the request using default priority
+ * iManager->GetThumbnailL( *source );
+ *
+ * // If GetThumbnailL() did not leave, the ThumbnailReady() callback is
+ * // now guaranteed to be called, unless the request is cancelled or
+ * // CThumbnailManager instance is deleted.
+ *
+ * // The source can be deleted immediately after issuing the request
+ * CleanupStack::PopAndDestroy( source );
+ * }
+ *
+ * CMyThumbnailControl::~CMyThumbnailControl()
+ * {
+ * // Bitmap should be destroyed before Thumbnail Manager
+ * delete iBitmap;
+ * delete iManager;
+ * }
+ *
+ * void CMyThumbnailControl::ThumbnailReady(
+ * TInt aError,
+ * MThumbnailData& aThumbnail,
+ * TThumbnailRequestId aId )
+ * {
+ * // This function must not leave.
+ *
+ * delete iBitmap; iBitmap = NULL;
+ * if ( !aError )
+ * {
+ * // Claim ownership of the bitmap instance for later use
+ * iBitmap = aThumbnail.DetachBitmap();
+ *
+ * // We can now use iBitmap in our Draw() method
+ * DrawDeferred();
+ * }
+ * else
+ * {
+ * // An error occurred while getting the thumbnail.
+ * // Perhaps we should show a broken image icon to the user.
+ * }
+ * }
+ *
+ * @endcode
+ *
+ * @lib thumbnailmanager.lib
+ * @since S60 v5.0
+ */
+NONSHARABLE_CLASS( CThumbnailManager ): public CBase
+ {
+public:
+ /**
+ * Flags for thumbnail creation.
+ * These can be combined using bitwise or.
+ */
+ enum TThumbnailFlags
+ {
+ /**
+ * Default flags. This means that:
+ * - Thumbnail must be as large as requested (unless the actual
+ * object is smaller).
+ * - Smaller thumbnails may be up scaled to desired resolution.
+ * - Aspect ratio is maintained and thumbnails are not cropped. The
+ * resulting thumbnail may smaller in either width or height if
+ * the aspect ratio of the object does not match the aspect ratio
+ * of the requested size.
+ */
+ EDefaultFlags = 0,
+
+ /**
+ * Allow thumbnails which are smaller than requested are. Thumbnail
+ * bitmaps are never up scaled if this flag is set.
+ */
+ EAllowAnySize = 1,
+
+ /**
+ * New thumbnail images are not created if this flag is set. Only
+ * existing thumbnails may be returned. If a requested thumbnail does
+ * not exist, KErrNotFound error is returned in ThumbnailReady()
+ * callback.
+ */
+ EDoNotCreate = 2,
+
+ /**
+ * Thumbnail images are cropped to match requested aspect ratio. If
+ * this flag is set, the size of the resulting thumbnail always
+ * matches the requested size.
+ */
+ ECropToAspectRatio = 4
+ };
+
+ /** Quality versus speed preference setting */
+ enum TThumbnailQualityPreference
+ {
+ /**
+ * Prefer thumbnails in the highest quality possible disregarding
+ * any negative impact on performance.
+ */
+ EOptimizeForQuality,
+
+ /**
+ * Get thumbnails as fast as possible, even if
+ * it means lower quality.
+ */
+ EOptimizeForPerformance,
+
+ /**
+ * Get lower quality preview thumbnail as fast as possible first and
+ * then a higher quality thumbnail later. The preview thumbnail is
+ * provided in the ThumbnailPreviewReady() callback and the high
+ * quality thumbnail in ThumbnailReady(). ThumbnailPreviewReady()
+ * is not get called at all if a suitable existing thumbnail is not
+ * found or if a high quality version is already available.
+ */
+ EOptimizeForQualityWithPreview
+ };
+
+ /**
+ * Two-phased constructor.
+ *
+ * @since S60 v5.0
+ * @param aObserver Observer to receive notifications about completed
+ * operations.
+ * @return New CThumbnailManager instance.
+ */
+ IMPORT_C static CThumbnailManager* NewL( MThumbnailManagerObserver&
+ aObserver );
+
+ /**
+ * Two-phased constructor.
+ *
+ * @since S60 v5.0
+ * @param aObserver Observer to receive notifications about completed
+ * operations.
+ * @return New CThumbnailManager instance (on cleanup stack).
+ */
+ IMPORT_C static CThumbnailManager* NewLC( MThumbnailManagerObserver&
+ aObserver );
+
+ /**
+ * Destructor
+ *
+ * @since S60 v5.0
+ */
+ virtual ~CThumbnailManager();
+
+ /**
+ * Get the current display mode for thumbnail bitmaps.
+ *
+ * @since S60 v5.0
+ * @return Current display mode for the thumbnail bitmaps.
+ */
+ virtual TDisplayMode DisplayMode()const = 0;
+
+ /**
+ * Set the current display mode for thumbnail bitmaps.
+ *
+ * @since S60 v5.0
+ * @param aDisplayMode New display mode value for the thumbnail bitmaps.
+ */
+ virtual void SetDisplayModeL( TDisplayMode aDisplayMode ) = 0;
+
+ /**
+ * Get the current quality versus performance preference.
+ *
+ * @since S60 v5.0
+ * @return Current quality versus performance preference.
+ */
+ virtual TThumbnailQualityPreference QualityPreference()const = 0;
+
+ /**
+ * Set quality versus performance preference.
+ *
+ * @since S60 v5.0
+ * @param aQualityPreference New quality versus performance preference
+ * value.
+ */
+ virtual void SetQualityPreferenceL( TThumbnailQualityPreference
+ aQualityPreference ) = 0;
+
+ /**
+ * Get the current desired size for thumbnail bitmaps.
+ *
+ * @since S60 v5.0
+ * @return Current desired size for thumbnail bitmaps (in pixels).
+ */
+ virtual const TSize& ThumbnailSize()const = 0;
+
+ /**
+ * Set desired size for thumbnail bitmaps.
+ *
+ * @since S60 v5.0
+ * @param aThumbnailSize New quality for the desired thumbnail size.
+ */
+ virtual void SetThumbnailSizeL( const TSize& aThumbnailSize ) = 0;
+
+
+ /**
+ * Get current flags for thumbnail generation.
+ *
+ * @since S60 v5.0
+ * @return Current flags.
+ */
+ virtual TThumbnailFlags Flags()const = 0;
+
+ /**
+ * Set flags for thumbnail generation. Several flags may be enabled
+ * by combining the values using bitwise or.
+ *
+ * @since S60 v5.0
+ * @param aFlags New flags.
+ */
+ virtual void SetFlagsL( TThumbnailFlags aFlags ) = 0;
+
+ /**
+ * Get a thumbnail for an object file. If a thumbnail already exists, it
+ * is loaded and if a thumbnail does not exist, it is created
+ * transparently. ThumbnailReady() callback will be called when the
+ * operation is complete. In addition, ThumbnailPreviewReady()
+ * callback may be called if EOptimizeForQualityWithPreview mode was
+ * defined.
+ *
+ * Current values for display mode, thumbnail size, flags and performance
+ * preference are used.
+ *
+ * @since S60 v5.0
+ * @param aObjectSource Source object or file
+ * @param aClientData Pointer to arbitrary client data.
+ * This pointer is not used by the API for
+ * anything other than returning it in the
+ * ThumbnailReady callback.
+ * @param aPriority Priority for this operation
+ * @return Thumbnail request ID. This can be used to
+ * cancel the request or change priority.
+ * The ID is specific to this CThumbnailManager
+ * instance and may not be shared with other
+ * instances.
+ */
+ virtual TThumbnailRequestId GetThumbnailL( CThumbnailObjectSource&
+ aObjectSource, TAny* aClientData = NULL, TInt aPriority = CActive
+ ::EPriorityStandard ) = 0;
+
+ /**
+ * Delete all thumbnails for a given object. This is an asynchronous
+ * operation, which always returns immediately.
+ *
+ * @since S60 v5.0
+ * @param aObjectSource Source object or file
+ */
+ virtual void DeleteThumbnails( CThumbnailObjectSource& aObjectSource ) = 0;
+
+ /**
+ * Create thumbnail for a given object. This is an asynchronous
+ * operation, which always returns immediately. No callbacks are
+ * emitted.
+ *
+ * @since S60 v5.0
+ * @param aObjectSource Source object or file
+ * @param aPriority Priority for this operation
+ * @return Thumbnail request ID. This can be used to
+ * cancel the request or change priority.
+ * The ID is specific to this CThumbnailManager
+ * instance and may not be shared with other
+ * instances.
+ */
+ virtual TThumbnailRequestId CreateThumbnails( CThumbnailObjectSource&
+ aObjectSource, TInt aPriority = CActive::EPriorityIdle ) = 0;
+
+ /**
+ * Cancel a thumbnail operation.
+ *
+ * @since S60 v5.0
+ * @param aId Request ID for the operation to be cancelled.
+ * @return Symbian OS error code or KErrNone if cancelling was
+ * successful.
+ */
+ virtual TInt CancelRequest( TThumbnailRequestId aId ) = 0;
+
+ /**
+ * Change the priority of a queued thumbnail operation.
+ *
+ * @since S60 v5.0
+ * @param aId Request ID for the request which to assign a new
+ * priority.
+ * @param aNewPriority New priority value
+ * @return Symbian OS error code or KErrNone if change was
+ * successful.
+ */
+ virtual TInt ChangePriority( TThumbnailRequestId aId, TInt aNewPriority ) =
+ 0;
+
+ /**
+ * Get a list of supported file formats for object files.
+ *
+ * The return value is a reference to a list that contains each
+ * supported MIME type. There may also be wildcards, such as "image/*".
+ *
+ * The returned reference is valid until CThumbnailManager is
+ * destroyed or GetSupportedMimeTypesL() is called again.
+ *
+ * @since S60 v5.0
+ * @return A list of supported MIME types. May contain wildcards.
+ * Ownership not transferred.
+ */
+ virtual const CDesCArray& GetSupportedMimeTypesL() = 0;
+
+ /**
+ * Delete thumbnails by TThumbnailId. This is an asynchronous
+ * operation, which always returns immediately.
+ *
+ * @since S60 v5.0
+ * @param aItemId TThumbnailId
+ */
+ virtual void DeleteThumbnails( const TThumbnailId aItemId ) = 0;
+
+/**
+ * Set desired size for thumbnail bitmaps.
+ *
+ * @since S60 v5.0
+ * @param aThumbnailSize Desired thumbnail size.
+ */
+ virtual void SetThumbnailSizeL( const TThumbnailSize aThumbnailSize ) = 0;
+
+ /**
+ * Get a persistent thumbnail for an object file. If a thumbnail already
+ * exists, it is loaded and if a thumbnail does not exist, it is created
+ * transparently. ThumbnailReady() callback will be called when the
+ * operation is complete. In addition, ThumbnailPreviewReady()
+ * callback may be called if EOptimizeForQualityWithPreview mode was
+ * defined.
+ *
+ * Current values for display mode, thumbnail size, flags and performance
+ * preference are used.
+ *
+ * @since S60 v5.0
+ * @param aThumbnailId Thumbnail ID
+ * @param aThumbnailSizeType Thumbnail size enumeration
+ * @param aClientData Pointer to arbitrary client data.
+ * This pointer is not used by the API for
+ * anything other than returning it in the
+ * ThumbnailReady callback.
+ * @param aPriority Priority for this operation
+ * @return Thumbnail request ID. This can be used to
+ * cancel the request or change priority.
+ * The ID is specific to this CThumbnailManager
+ * instance and may not be shared with other
+ * instances.
+ */
+ virtual TThumbnailRequestId GetThumbnailL( const TThumbnailId aThumbnailId,
+ TAny* aClientData = NULL,
+ TInt aPriority = CActive::EPriorityStandard ) = 0;
+
+
+ /**
+ * Set a thumbnail for an object file generated from buffer delivered in source
+ * object. ThumbnailReady() callback will be called when the
+ * operation is complete. In addition, ThumbnailPreviewReady()
+ * callback may be called if EOptimizeForQualityWithPreview mode was
+ * defined.
+ *
+ * Current values for display mode, thumbnail size, flags and performance
+ * preference are used.
+ *
+ * @since S60 v5.0
+ * @param aThumbnailId Thumbnail ID
+ * @param aThumbnailSizeType Thumbnail size enumeration
+ * @param aClientData Pointer to arbitrary client data.
+ * This pointer is not used by the API for
+ * anything other than returning it in the
+ * ThumbnailReady callback.
+ * @param aPriority Priority for this operation
+ * @return Thumbnail request ID. This can be used to
+ * cancel the request or change priority.
+ * The ID is specific to this CThumbnailManager
+ * instance and may not be shared with other
+ * instances.
+ */
+ virtual TThumbnailRequestId SetThumbnailL( CThumbnailObjectSource& aObjectSource,
+ TAny* = NULL,
+ TInt aPriority = CActive::EPriorityIdle ) = 0;
+
+
+ /**
+ * Import an image to be used as thumbnail for an object. If a
+ * thumbnail already exists, it is loaded and if a thumbnail does not
+ * exist, it is created transparently. ThumbnailReady() callback will be
+ * called when the operation is complete. In addition, ThumbnailPreviewReady()
+ * callback may be called if EOptimizeForQualityWithPreview mode was
+ * defined.
+ *
+ * Current values for display mode, thumbnail size, flags and performance
+ * preference are used.
+ *
+ * @since S60 v5.0
+ * @param aObjectSource Source object or file
+ * @param aTargetUri Target URI to which the imported thumbnail is linked.
+ * @param aClientData Pointer to arbitrary client data.
+ * This pointer is not used by the API for
+ * anything other than returning it in the
+ * ThumbnailReady callback.
+ * @param aPriority Priority for this operation
+ * @return Thumbnail request ID. This can be used to
+ * cancel the request or change priority.
+ * The ID is specific to this CThumbnailManager
+ * instance and may not be shared with other
+ * instances.
+ */
+ virtual TThumbnailRequestId ImportThumbnailL( CThumbnailObjectSource& aObjectSource,
+ const TDesC& aTargetUri, TAny* aClientData = NULL,
+ TInt aPriority = CActive::EPriorityIdle ) = 0;
+
+ /**
+ * Update Thumbnails by TThumbnailId. This is an asynchronous
+ * operation, which always returns immediately.
+ *
+ * @since S60 v5.0
+ * @param aItemId TThumbnailId
+ * @param aPath (New) path for the Thumbnail
+ * @param aOrientation Thumbnail orientation
+ * @param aModified Last modified
+ */
+ virtual void UpdateThumbnailsL( const TThumbnailId aItemId, const TDesC& aPath,
+ const TInt aOrientation, const TInt64 aModified, const TInt aPriority ) = 0;
+
+};
+
+#endif // THUMBNAILMANAGER_H