/*
* 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:  Base class for thumbnail provider plug-ins
 *
*/


#ifndef THUMBNAILPROVIDER_H
#define THUMBNAILPROVIDER_H

#include <ecom/ecom.h>
#include <apmstd.h>

#include "thumbnailmanager.h" // TThumbnailFlags
#include "thumbnaillog.h"

/**
 *  Thumbnail provider observer class
 *
 *  @since S60 v5.0
 */
class MThumbnailProviderObserver
    {
public:
    /**
     * Thumbnail provider observer callback to notify the server when
     * thumbnail has been generated.
     *
     * @since S60 5.0
     * @param aError Error code
     * @param aBitmap Thumbnail bitmap. The observer implementation will
     *                assume ownership of the bitmap.
     * @param aOriginalSize Original size of the object in pixels.
     * @param aEXIF ETrue if thumbnail origin is EXIF.
     */
    virtual void ThumbnailProviderReady( TInt aError, CFbsBitmap* aBitmap,
        const TSize& aOriginalSize, const TBool aEXIF, const TBool aPortrait  ) = 0;
};


/**
 *  Base class for thumbnail provider plug-ins.
 *
 *  @since S60 v5.0
 */
class CThumbnailProvider: public CBase
    {
public:
    /**
     * Create a provider instance. The instance is identified
     * by the implementation UID.
     */
    static CThumbnailProvider* NewL( TUid aUid );

    /**
     * Get the UID of this provider.
     *
     * @since S60 5.0
     * @return Provider implementation UID
     */
    TUid Uid();

    /**
     * Set the observer to receive notification
     * about thumbnail generation completion.
     *
     * @since S60 5.0
     * @param aObserver Reference to the observing object. Ownership not
     *                  transferred.
     */
    void SetObserver( MThumbnailProviderObserver& aObserver );

    /**
     * Set the target size for uncropped thumbnails. The actual thumbnail
     * at least this wide or high, depending on which is the limiting
     * factor.
     *
     * @since S60 5.0
     * @param aSize Target size in pixels for uncropped thumbnails.
     */
    void SetTargetSize( const TSize& aSize );

    /**
     * Set the target size for cropped thumbnails. The actual thumbnail
     * at least this large and it will include the whole thumbnail,
     * not just the cropped portion.
     *
     * @since S60 5.0
     * @param aCroppedSize Target size in pixels for cropped thumbnails.
     */
    void SetCroppedTargetSize( const TSize& aCroppedSize );

    /**
     * Reset thumbnail parameters to defaults.
     */
    void Reset();

    /**
     * Get thumbnail bitmap. Must be implemented by provider plug-ins.
     *
     * @since S60 5.0
     * @param aFs File server session that can be used
     * @param aFile File handle to the object file
     * @param aMimeType MIME-type of the object file.
     * @param aFlags Thumbnail generation flags
     * @param aDisplayMode Display mode
     */
    virtual void GetThumbnailL( RFs& aFs, RFile64& aFile, const TDataType&
        aMimeType, const CThumbnailManager::TThumbnailFlags aFlags, const
        TDisplayMode aDisplayMode, const CThumbnailManager::TThumbnailQualityPreference aQualityPreference ) = 0;
  
    /**
     * Get thumbnail bitmap. Must be implemented by provider plug-ins.
     *
     * @since S60 5.0
     * @param aFs File server session that can be used
     * @param aBuffer object buffer
     * @param aMimeType MIME-type of the object file.
     * @param aFlags Thumbnail generation flags
     * @param aDisplayMode Display mode
     */    
    virtual void GetThumbnailL( RFs& aFs, TDesC8* aBuffer, const
        TDataType& aMimeType, const CThumbnailManager::TThumbnailFlags aFlags,
        const TDisplayMode aDisplayMode, const CThumbnailManager::TThumbnailQualityPreference aQualityPreference  ) = 0;  
    
    /**
     * Get thumbnail bitmap. Must be implemented by provider plug-ins.
     *
     * @since S60 5.0
     * @param aFs File server session that can be used
     * @param aBuffer object buffer
     */
    
    virtual void GetThumbnailL( RFs& aFs, TDesC8& aBuffer) = 0;

    /**
     * Cancel a previous thumbnail request, if any.
     *
     * @since S60 5.0
     */
    virtual void CancelGetThumbnail() = 0;

    virtual ~CThumbnailProvider(){}

protected:
    /**
     * Get the actual target size for the thumbnail.
     * This is the maximum of the non-cropped and cropped
     * target sizes.
     *
     * @since S60 5.0
     */
    inline void ResolveSize();

    /**
     * Calculate the scaled down size for the thumbnail.
     * Aspect ratio is always preserved. If cropping is disabled
     * the resulting size at most as wide or tall as requested.
     * If cropping is enabled, the result is at least as wide
     * and as tall as requested (unless original size is smaller
     * than requested).
     *
     * @since S60 5.0
     * @param aOriginalSize Original size in pixels
     * @param aTargetSize Target size in pixels
     * @param aCrop Enable cropping
     * @return Result size
     */
    inline TSize FitToSize( const TSize& aOriginalSize, const TSize&
        aTargetSize, TBool aCrop );

protected:
    /**
     * Provider observer. Implemented by thumbnail generation task.
     * Not own.
     */
    MThumbnailProviderObserver* iObserver;

    /**
     * Thumbnail generation flags.
     */
    CThumbnailManager::TThumbnailFlags iFlags;

    /**
     * Thumbnail generation flags.
     */
    CThumbnailManager::TThumbnailQualityPreference iQualityPreference;

    /**
     * Size of the original object.
     */
    TSize iOriginalSize;

    /**
     * Target size for uncropped thumbnails.
     */
    TSize iTargetSize;

    /**
     * Target size for cropped thumbnails.
     */
    TSize iCroppedTargetSize;

    /**
     * Display mode for thumbnail bitmap
     */
    TDisplayMode iDisplayMode;

    /**
     * ECOM plug-in destructor key.
     */
    TUid iDtor_ID_Key;

    /**
     * UID of this implementation.
     */
    TUid iUid;
};


#endif // THUMBNAILPROVIDER_H