/*
* 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 MNcdNode interface
*
*/


#ifndef M_NCD_NODE_H
#define M_NCD_NODE_H


#include <e32cmn.h>
#include <e32std.h>

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


class MNcdNodeContainer;
class MNcdLoadNodeOperation;
class MNcdLoadNodeOperationObserver;
class MNcdOperation;


/**
 *  Node contains the basic information about the content.
 *  The interface also provides a load function that must be used to
 *  initialize the node, before accessing other information.
 *
 *  When the UI gets the node, the node may not contain any information
 *  except from the node state. The state may be checked by calling
 *  MNcdNode::State(). MNcdNode::LoadL() can then be called to load
 *  the content for the node, if the state is uninitialized or expired.
 *
 *  @note The actual content information, such as name, description etc. are
 *  available through the MNcdNodeMetadata interface that can be queried from
 *  node objects. There are various other additional node interfaces as well
 *  that all offer different functionality and information about the node. The
 *  interfaces are not available at all times, they have different criteria for
 *  becoming available. For example, the MNcdNodeMetadata interface becomes
 *  available for a node when its metadata is loaded, so if it is not available
 *  at first, it can be made available by calling the node's MNcdNode::LoadL()
 *  method.
 *
 *  
 *  @see MNcdNodeMetadata
 *  @see MNcdNodeContainer
 *  @see MNcdNodeContent
 *  @see MNcdNodeDependency
 *  @see MNcdNodeDownload
 *  @see MNcdNodeIcon
 *  @see MNcdNodeInstall
 *  @see MNcdNodePreview
 *  @see MNcdNodePurchase
 *  @see MNcdNodeScreenshot
 *  @see MNcdNodeSearch
 *  @see MNcdNodeSkin
 *  @see MNcdNodeSubscribe
 *  @see MNcdNodeUpgrade
 *  @see MNcdNodeUriContent
 *  @see MNcdNodeUserData
 */
class MNcdNode : public virtual MCatalogsBase
    {

public:

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


    /**
     * TNcdNode::TState gives information in what state the node is at the moment.
     * This information can be used to check if the node information should be
     * loaded over network or from local cache.
     *
     * 
     */
    enum TState
        {
        /**
         * Node is not initialized and the data should
         * be loaded from either local cache, or over network.
         */
        EStateNotInitialized,

        /** Node data is up to date. */
        EStateInitialized,

        /** Node data is expired and should be reloaded over network. */
        EStateExpired
        };


    /**
     * Gives information about the state of the node. This information can be used to
     * check whether the item data has been loaded or if the data is expired.
     * 
     * 
     * @return The state of the node.
     */
    virtual TState State() const = 0;


    /**
     * Gets the node id.
     *
     * 
     * @return Id of the node.
     */
    virtual const TDesC& Id() const = 0;


    /**
     * All nodes and their content are part of a namespace. Within the
     * namespace, node identifiers are unique. This function returns the namespace
     * of this node and its contents.
     *
     * 
     * @return The namespace identifier. If the protocol has not defined
     *         any value, an empty descriptor is returned.
     */
    virtual const TDesC& Namespace() const = 0;


    /**
     * Gets the name of the catalog source for the node.
     *
     * 
     * @return Name of the catalog source where the node is loaded from. An
     *  empty string is returned if the source name is not defined.
     */
    virtual const TDesC& CatalogSourceName() const = 0;


    /**
     * Retrieves the reference to the parent of this node.
     *
     * 
     * @return The parent of this node. NULL if the node
     *  has no parent. Counted, Release() must be called
     *  after use.
     * @exception Leave System wide error code, 
     *  KErrNotFound if the parent node is not loaded.
     */
    virtual MNcdNodeContainer* ParentL() const = 0;
    

    /**
     * Loads node information from the content provider.
     *
     * @note Should be called when a folder node needs to be refreshed, clears all
     *  child nodes for folders!
     *
     * 
     * @param aObserver Observer for the operation.
     * @return Pointer to an operation object that can be
     *  used to check the loading progress. Counted, Release() must be called
     *  after use.     
     * @exception Leave System wide error code.
     *  KNcdErrorParallelOperationNotAllowed if a parallel client is running
     *  an operation for the same metadata. See MNcdOperation for full explanation.
     */
    virtual MNcdLoadNodeOperation* LoadL( MNcdLoadNodeOperationObserver& aObserver ) = 0;


    /**
     * Returns a list of currently active operations of this node for progress
     * monitoring and operation management.
     *
     * @note Operations may also be other than just MNcdLoadNodeOperations.
     *
     * @return List of currently active operations for the node. Counted,
     *  each pointer must be released after use e.g. with a call to the array's
     *  RCatalogsArray::ResetAndDestroy().
     * @exception Leave System wide error code
     */
    virtual RCatalogsArray< MNcdOperation > OperationsL() const = 0;
    
    
    /**
     * Adds the node to favorite nodes. If the node is already
     * a favorite node, does nothing.
     *
     * @exception Leave System wide error code 
     */
    virtual void AddToFavoritesL() = 0;
        
    
protected:

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


#endif // M_NCD_NODE_H