/*

* Copyright (c) 2002-2005 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: 

*     Class which loads a image from a image field.

*     This class can be used for image and image for call loading.

*

*/

#ifndef __CPbkImageManager_H__

#define __CPbkImageManager_H__

//  INCLUDES

#include <e32base.h>

#include <PbkFields.hrh> // TPbkFieldId

//  FORWARD DECLARATIONS

class CPbkContactEngine;

class MPbkImageOperation;

class MPbkImageGetObserver;

class CPbkContactItem;

class MPbkImageGetImageObserver;

class MPbkImageSetObserver;

class CFbsBitmap;

class TPbkImageLoadParameters;

class CPbkObserverAdapter;

// CLASS DECLARATIONS

/**

 * Phonebook image manager. Contains operations for attaching, removing and

 * querying images connected to Phonebook contacts.

 *

 * For all thumbnail images all the Set* operations convert the image to full 

 * color (24 bits/pixel) JPEG format and scale it to KPbkPersonalImageSize 

 * before connecting the image to a contact. Scaling does not change image's 

 * aspect ratio.

 * If the original image is in JPEG format and its size is <=KPbkPersonalImageSize

 * a copy of the original image is stored directly.

 *

 * For all call object images all the Set* operations convert the image to full 

 * color (24 bits/pixel) JPEG format and scale it to the total area of the 

 * screen available to the application before connecting the image to a contact. 

 * Scaling does not change image's aspect ratio.

 * If the original image is in JPEG format and its size is <= 

 * the application screen area

 * a copy of the original image is stored directly.

 * 

 * @see MPbkImageGetObserver

 * @see MPbkImageSetObserver

 */

class CPbkImageManager : public CBase

    {

    public: // Interface

        /**

         * Creates and returns a new image manager.

         * If given phonebook field id is something else than 

         * EPbkFieldIdThumbnailImage or EPbkFieldIdCODImageID then

         * "CPbkImageManager 1" panic will occur.

         * @param aEngine   Phonebook contact engine

         * @param aFieldId  Phonebook field type id of fetched image.

         * If id is something else than EPbkFieldIdThumbnailImage or 

         * EPbkFieldIdCodImageID then a EPbkInvalidArgument panic will occur.         

         */

        IMPORT_C static CPbkImageManager* NewL(CPbkContactEngine& aEngine);

        /**

         * Destructor.

         */

        ~CPbkImageManager();

        /**

         * Gets a image bitmap from a contact asynchronously.

         *

         * @param aFieldId  Phonebook field type id of fetched image.

         * @param aObserver     Observer for this operation.

         * @param aContactItem  Contact to retrieve the image from.

         * @return  a image operation object. Caller deletes the object 

         *          when the operation is done or needs to be canceled.

         */

        IMPORT_C MPbkImageOperation* GetImageAsyncL(

                TPbkFieldId aFieldId,

                MPbkImageGetObserver& aObserver, 

                const CPbkContactItem& aContactItem);

        /**

         * Gets a parameterized image bitmap

         * from a contact asynchronously.

         *

         * @param aFieldId  Phonebook field type id of fetched image.

         * @param aObserver     Observer for this operation.

         * @param aContactItem  Contact to retrieve the image from.

         * @param aParams       Parameters for bitmap, see TPbkImageLoadParameters.

         *                      NOTE: iFrameNumber parameter has no meaning.

         *                      

         * @return  an image operation object. Caller deletes the object 

         *          when the operation is done or needs to be canceled.

         * @see TPbkImageLoadParameters

         */

        IMPORT_C MPbkImageOperation* GetImageAsyncL(

                TPbkFieldId aFieldId,

                MPbkImageGetObserver& aObserver, 

                const CPbkContactItem& aContactItem,

                TPbkImageLoadParameters& aParams);

        /**

         * Gets a image from a contact asynchronously.

         *

         * @param aFieldId  Phonebook field type id of fetched image.

         * @param aObserver     Observer for this operation.

         * @param aContactItem  Contact to retrieve the image from.

         * @return  an image operation object. Caller deletes the object 

         *          when the operation is done or needs to be canceled.

         */

        IMPORT_C MPbkImageOperation* GetImageAsyncL(

                TPbkFieldId aFieldId,

                MPbkImageGetImageObserver& aObserver, 

                const CPbkContactItem& aContactItem);

        /**

         * Sets a image image for a contact asynchronously.

         *

         * @param aFieldId  Phonebook field type id of fetched image.

         * @param aObserver     Observer for this operation.

         * @param aContactItem  Contact to set the image to.

         * @param aBitmap       Bitmap to set as the image for aContact.

         * @return  an image operation object. Caller deletes the object 

         *          when the operation is done or needs to be canceled.

         */

        IMPORT_C MPbkImageOperation* SetImageAsyncL(

                TPbkFieldId aFieldId,

                MPbkImageSetObserver& aObserver, 

                CPbkContactItem& aContactItem, 

                const CFbsBitmap& aBitmap);

        /**

         * Sets a image image for a contact asynchronously.

         *

         * @param aFieldId  Phonebook field type id of fetched image.

         * @param aObserver     Observer for this operation.

         * @param aContactItem  Contact to set the image to.

         * @param aImageBuffer  image buffer to set as the image for aContact.

         * @return  an image operation object. Caller deletes the object 

         *          when the operation is done or needs to be canceled.

         */

        IMPORT_C MPbkImageOperation* SetImageAsyncL(

                TPbkFieldId aFieldId,

                MPbkImageSetObserver& aObserver, 

                CPbkContactItem& aContactItem, 

                const TDesC8& aImageBuffer);

        /**

         * Sets a image image for a contact asynchronously.

         *

         * @param aFieldId  Phonebook field type id of fetched image.

         * @param aObserver     Observer for this operation.

         * @param aContactItem  Contact to set the image to.

         * @param aFileName     File name for a image to set as the image for aContact.

         * @return  an image operation object. Caller deletes the object 

         *          when the operation is done or needs to be canceled.

         */

        IMPORT_C MPbkImageOperation* SetImageAsyncL(

                TPbkFieldId aFieldId,

                MPbkImageSetObserver& aObserver, 

                CPbkContactItem& aContactItem, 

                const TDesC& aFileName);

        /**

         * Returns true if aContactItem has a image image attached to it.

         * @param aFieldId  Phonebook field type id of fetched image.

         * @param aContactItem Contact that is queried for image.

         * @return ETrue if given contact has a image, EFalse otherwise.

         */

        IMPORT_C TBool HasImage(

                TPbkFieldId aFieldId, 

                const CPbkContactItem& aContactItem) const;

        /**

         * Removes any image from aContactItem.

         * @param aFieldId  Phonebook field type id of fetched image.

         * @param aContactItem Contact whose image is removed.

         */

        IMPORT_C void RemoveImage(

                TPbkFieldId aFieldId,

                CPbkContactItem& aContactItem);

    private: // Implementation

        CPbkImageManager(CPbkContactEngine& aEngine);

        void ConstructL();

    private: // Data members

        /// Ref: contact engine

        CPbkContactEngine& iEngine;

        /// Owns: handles adaptation of different observer APIs

        CPbkObserverAdapter* iPbkObserverAdapter;

    };

/**

 * Abstract asynchronous image operation. The operation can be cancelled by

 * deleting it.

 *

 * @see CPbkImageManager

 */ 

class MPbkImageOperation

    {

    public:  // Interface

        /**

         * Destructor. Cancels this image operation and releases any 

         * resources held by it.

         */

        virtual ~MPbkImageOperation() = 0;

    };

inline  MPbkImageOperation::~MPbkImageOperation()

    {

    }

#endif // __CPbkImageManager_H__

// End of File