/*

* 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 MNcdNodeUpgrade interface

*

*/

#ifndef M_NCD_NODE_UPGRADE_H

#define M_NCD_NODE_UPGRADE_H

#include "catalogsbase.h"

#include "ncdinterfaceids.h"

#include "catalogsarray.h"

class MNcdNode;

/**

 *  This interface is provided for the node if this node

 *  contains an upgrade to the content of some other node.

 *  UI may use this interface to check if the node contains

 *  an upgrade.

 *

 *  This interface is available:

 *

 *  If the content of this node has been updated to server after the 

 *  node was bought or this node upgrades some installed application, 

 *  see EUpgradeContent

 *

 *  If this node upgrades some other node, see EUpgradeNode

 *

 *  This interface is NOT available if there is nothing to upgrade even if

 *  the upgrades-dependency is defined in the protocol.

 *

 *  

 */

class MNcdNodeUpgrade : public virtual MCatalogsBase

    {

public:

    /**

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

     *

     * 

     */

    enum { KInterfaceUid = ENcdNodeUpgradeUid };

    enum TUpgradeType

        {

        /**

         * Upgrades some other node

         * @see UpgradeableNodeL()

         */

        EUpgradeNode,

        /**

         * The server contains an upgrade for the content of this

         * node

         *

         * This is used if the id in <downloadableContent> 

         * matches some installed application and the application's version

         * number is lower than the one in <downloadableContent> or

         * if the protocol defines an upgrades-dependency to

         * some application and that application is installed on the device

         *

         * @see MNcdNodeContentInfo

         */

        EUpgradeContent,

        /**

         * Upgrade type is set to EUpgradeNotAvailable when the upgrade

         * is installed.

         */

        EUpgradeNotAvailable

        };

    /**

     * Retrieves the name of the upgrade content in text format.

     *

     * 

     * @return Name of the upgrade content. If the protocol has not defined any value

     *         for name, an empty descriptor is returned.

     */

    virtual const TDesC& Name() const = 0;

    /**

     * This function is the indicative Symbian application UID for the

     * upgrade content that is an application. This can be used e.g. for checking

     * if the application has already been installed to the phone.

     *

     * @return The UID of the upgrade application item.

     */

    virtual TUid Uid() const = 0;

    /**

     * Different versions of the content items may exist. Thus,

     * a version identifier may be defined for the item. When installing

     * applications the version may be required.

     *

     * @return Version string of the upgrade application item.  

     * If the protocol has not defined any value, an empty string is returned.

     */

    virtual const TDesC& Version() const = 0;

    /**

     * Gives the target node that this node may upgrade.

     *

     * @note The reference count of the returned node object 

     * is increased by one. So, Release function of the node 

     * should be called when the node is not needed anymore.

     *

     * @note If the upgrade target has been directly gotten as a content

     * instead of as a node, then NULL pointer is returned here. Name, Uid and Version

     * information about the upgrade target content can still be requested by using

     * the other functions of this interface.

     *

     * @return Pointer to the target node that this node upgrades.

     *  NULL if the upgrade target has been given as a content intead of as a node.

     *  Counted, Release() must be called after use.

     * @exception Leave System wide error codes.

     */

    virtual MNcdNode* UpgradeableNodeL() const = 0;

    /**

     * Upgrade type getter

     *

     * @return Type of the upgrade

     * @see TUpgradeType

     */     

    virtual TUpgradeType UpgradeType() const = 0;

protected:

    /**

     * Destructor.

     *

     * @see MCatalogsBase::~MCatalogsBase

     */

    virtual ~MNcdNodeUpgrade() {}

    };

#endif // M_NCD_NODE_UPGRADE_H