/*
* Copyright (c) 2006 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 MNcdNodePreview
*
*/


#ifndef M_NCD_NODE_PREVIEW_H
#define M_NCD_NODE_PREVIEW_H


#include <e32cmn.h>

#include "catalogsbase.h"
#include "ncdinterfaceids.h"


class MNcdDownloadOperation;
class MNcdDownloadOperationObserver;
class RFile;

/**
 *  This interface is provided if the node contains preview content.
 *  One node may contain multiple preview items.
 *
 *  
 */
class MNcdNodePreview : public virtual MCatalogsBase
    {

public:

    /**
     * Unique identifier for the interface, required for all MCatalogsBase interfaces.
     *
     * 
     */
    enum { KInterfaceUid = ENcdNodePreviewUid };


    /**
     * Gives the number of previews of the node.
     *
     * @note This count is given according to the protocol information
     * that informs how many previews are available. So, the information
     * can be asked before calling LoadPreviewL. But, to get the
     * data of the wanted preview, LoadPreviewL has to be called.
     *
     * @return The number of preview items.
     */
    virtual TInt PreviewCount() const = 0;


    /**
     * IsPreviewLoadedL informs if the preview has already been loaded for the
     * node. Then, call of LoadPreviewL is not necessary.
     *
     * @param aIndex tells which one of the previews is wanted.
     * @return ETrue if the preview has already been loaded, EFalse otherwise.
     * @exception Panic ENcdPanicIndexOutOfRange Array index out of range.
     */
    virtual TBool IsPreviewLoadedL( TInt aIndex ) const = 0;


    /**
     * Gives the mime type of the preview data.
     *
     * This mime type is set according to the information gotten
     * from the protocol if any. So, this information is available before 
     * calling LoadPreviewL for the preview item of the given index. 
     *
     * @note If the mime type is not received in protocol responses, it is
     * taken from Content-Type HTTP header after the preview has been downloaded
     * successfully
     *
     * @param aIndex tells which one of the previews is wanted.
     * @return The mime type of the preview 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, KNullDesC is returned.
     * @exception Panic ENcdPanicIndexOutOfRange Array index out of range.
     */
    virtual const TDesC& PreviewMimeType( TInt aIndex ) const = 0;


    /**
     * Loads the preview data from the internet.
     *
     * @note The reference count of the operation object is increased by one. 
     * So, Release() function of the operation should be called when operation 
     * is not needed anymore.
     *
     * @param aIndex tells which one of the previews is wanted.
     * @param aObserver Observer for the operation.
     * @return Pointer to an operation object that handles
     *  the preview data downloading. This operation can be used
     *  to check the progressing of the preview download. 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.
     * @exception Panic ENcdPanicIndexOutOfRange Array index out of range.
     */
    virtual MNcdDownloadOperation* LoadPreviewL( TInt aIndex,
        MNcdDownloadOperationObserver* aObserver ) = 0;


    /**
     * Gives the preview data file.
     *
     * @note RFile handle can be used to get the unifying id for example
     * using RFile::FullName.
     * @note The MIME type of the preview may be found automatically
     * from the preview data by Symbian methods.
     *
     * @param aIndex tells which one of the previews is wanted. 
     * @return Handle to a file containing the preview data. Ownership is transferred.
     *  So, the user has to call Close when the file is not needed anymore.
     * @exception KErrNotFound if the corresponding preview data 
     *  has not been downloaded for the specified preview item.
     * @exception Leave System wide error codes.
     * @exception Panic ENcdPanicIndexOutOfRange Array index out of range.
     */
    virtual RFile PreviewFileL( TInt aIndex ) const = 0;


protected:

    /**
     * Destructor.
     * 
     * @see MCatalogsBase::~MCatalogsBase()
     */
    virtual ~MNcdNodePreview() {}

    };


#endif // M_NCD_NODE_PREVIEW_H