/*

* Copyright (c) 2006-2008 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:   Contains MNcdNodeIcon interface

*

*/

#ifndef M_NCD_NODE_ICON_H

#define M_NCD_NODE_ICON_H

#include <e32cmn.h>

#include "catalogsbase.h"

#include "ncdinterfaceids.h"

class MNcdDownloadOperation;

class MNcdDownloadOperationObserver;

/**

 *  Provides functions to handle the icon of the node.

 *  This interface supposes that a node has only one icon.

 *  The MIME type of the icon may be found automatically

 *  from the icon data by Symbian methods.

 *

 *  

 */

class MNcdNodeIcon : public virtual MCatalogsBase

    {

public:

    /**

     * Unique identifier for the interface, required for all MCatalogsBase interfaces.

     *

     * 

     */

    enum { KInterfaceUid = ENcdNodeIconUid };

    /**

     * Gives the icon id. This id can be used by UI

     * to identify icons that have already been retrieved by LoadIconL.

     * So, icons can be more efficiently shared between different nodes.

     * 

     * 

     * @return Id of the loaded icon. If the protocol has not defined

     * any value, an empty string is returned.

     */

    virtual const TDesC& IconId() const = 0;

    /**

     * Gives the mime type of the icon data.

     *

     * @note This mime type is set according to the information gotten

     * from the protocol. So, this information is available before calling

     * LoadIconL for the icon item of the given index.

     *

     * @note Current implementation returns always KNullDesC

     * 

     * @return The mime type of the icon data. The type is

     * given as a text according to the standards that define MIME types.

     * Ownership is transferred. If the protocol has not defined

     * any value, an empty string is returned.

     */

    virtual const TDesC& IconMimeType() const = 0;

    /**

     * Downloads the icon file. The icon is not handled by the engine,

     * the icon data should be handled by the user of this interface as it sees fit.

     *

     * @note The reference count of the operation object is increased by one. 

     * So, Release() function of the operation should be called when the operation 

     * is not needed anymore.

     *

     * @note If a download operation has already been started for the specified

     *  icon, the already existing operation object is returned.

     *

     * 

     * @param aObserver Observer for the operation. NULL if no observer

     *  should be called. Will override previous observer

     *  for the operation, in case the operation already existed. 

     * @return Pointer to an operation object that can 

     * be used to check the progressing of the icon loading operation. Counted,

     * Release() must be called after use.

     * @exception Leave System wide error codes.

     *  KNcdErrorParallelOperationNotAllowed if a parallel client is running

     *  an operation for the same metadata. See MNcdOperation for full explanation.

     */ 

    virtual MNcdDownloadOperation* LoadIconL( 

        MNcdDownloadOperationObserver* aObserver ) = 0;

    /**

     * Gives the data of the loaded icon.

     *

     * 

     * @return Pointer to data of the loaded icon. Ownership is transferred.

     * A NULL pointer if the icon has not been loaded for the node.

     * @exception Leave System wide error codes.

     */

    virtual HBufC8* IconDataL() = 0;

protected:

    /**

     * Destructor.

     * 

     * @see MCatalogsBase::~MCatalogsBase()

     */

    virtual ~MNcdNodeIcon() {}

    };

#endif // M_NCD_NODE_ICON_H