/*

* 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:   ?Description

*

*/

#ifndef M_NCD_PURCHASE_OPTION_H

#define M_NCD_PURCHASE_OPTION_H

#include <e32cmn.h>

#include "catalogsbase.h"

#include "ncdinterfaceids.h"

class MNcdNode;

class MNcdSubscription;

/**

 *  Describes one purchase option. 

 *

 *  Each purchasable node may have one or more of these.

 *  A purchase option can be for example "1$ Trial version", or "10$ Full version".

 *

 *  

 */

class MNcdPurchaseOption : public virtual MCatalogsBase

    {

public:

    /**

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

     *

     * 

     */

    enum { KInterfaceUid = ENcdPurchaseOptionUid };

    /**

     * Type of the purchase option.

     */

    enum TType

        {

        /** Purchase option to make a normal purchase. */

        EPurchase,

        /** Purchase option to purchase a subscription. */

        ESubscription,

        /** Purchase option to do a purchase using an existing subscription. */

        ESubscriptionPurchase,

        /** Purchase option to do an upgrade to an existing subscription. */

        ESubscriptionUpgrade

        };

    /**

     * Name getter.

     *

     * 

     * @return Name of the purchase option.

     */ 

    virtual const TDesC& Name() const = 0;

    /**

     * Price getter.

     *

     * 

     * @return String indicating the price of the purchase option.

     */

    virtual const TDesC& Price() const = 0;

    /**

     * Checks whether this purchase option is free.

     *

     * 

     * @return ETrue if this purchase option is free.

     */

    virtual TBool IsFree() const = 0;

    /**

     * Get type of the purchase option.

     *

     * 

     * @return Subscription type.

     */

    virtual TType PurchaseOptionType() const = 0;

    /**

     * Checks whether this purchase option is obsolete or not.

     * Purchase option becomes obsolete if it is removed while

     * user still has reference to it. Removal can be done for

     * example because the purchase option was removed from the

     * server.

     * Obsolete purchase option should not be used and valid purchase

     * option instances should be retrieved by using PurchaseOptionsL

     * method from MNcdNodePurchase interface.

     *

     * 

     * @return ETrue if this purchase option is obsolete.

     */

    virtual TBool IsObsolete() const = 0;

    /**

     * Checks whether this purchase option can be used.

     * The purchase option cannot be used if the type of

     * this purchase option is ESubscriptionPurchase or

     * ESubscriptionUpgrade and the parentsubscription is

     * not yet bought.

     *

     * 

     * @return ETrue if this purchase option can be used.

     * @exception Leave with KNcdErrorObsolete if this purchase option

     *            is obsolete. Otherwise leave with System wide error code.

     */

    virtual TBool IsUsableL() const = 0;

    /**

     * If this purchase option is of type ESubscriptionPurchase,

     * this function returns the subscription that the purchase option

     * uses if the subscription exists in subscription manager.

     *

     * @note Valid only when purchase option is a valid

     *       ESubscriptionPurchase and this purchase option is 

     *       not obsolete.

     *

     * @return Pointer to the subscription that this purchase option

     *         uses. The subscription can be expired or not, but if

     *         the subscription does not exist in the subscription

     *         manager, NULL is returned.

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

     *

     * @exception Leave with KNcdErrorObsolete if this purchase option

     *            is obsolete. If this purchase option is not valid

     *            ESubscriptionPurchase then leave with

     *            KNcdErrorPurchaseOptionNotValidSubscriptionPurchase.

     *            Otherwise leave with System wide error code.

     */

    virtual MNcdSubscription* ParentSubscriptionL() const = 0;

    /**

     * Returns the node that has the purchase option to buy

     * the subscription needed to use this purchase option.

     *

     * @note Valid only when purchase option is a valid

     *       ESubscriptionPurchase and this purchase option is 

     *       not obsolete.

     *

     * @return Pointer to the node that has the purchase option to buy

     *         the subscription needed to use this purchase option.

     *         Note that the node may be in an uninitialized state,

     *         or in an initialized state, depending on whether the

     *         node has previously been known to the engine. Counted,

     *         Release() must be called after use.

     *

     * @exception Leave with KNcdErrorObsolete if this purchase option

     *            is obsolete. If this purchase option is not valid

     *            ESubscriptionPurchase then leave with

     *            KNcdErrorPurchaseOptionNotValidSubscriptionPurchase.

     *            Otherwise leave with System wide error code.

     */

    virtual MNcdNode* ParentSubscriptionNodeL() const = 0;

    /**

     * Returns an id that identifies the purchaseoption that can be

     * used to buy the subscription needed to use this purchase option.

     * Node that has the purchase option identified by the id returned

     * from this function can be queried by using method

     * ParentSubscriptionNodeL().

     *

     * @note Valid only when purchase option is a valid

     *       ESubscriptionPurchase.

     *

     * @return Id that identifies the purchaseoption that can be

     *         used to buy the subscription needed to use this 

     *         purchase option. Node where from this purchase option is

     *         found can be queried by using method

     *         ParentSubscriptionNodeL().

     *

     * @exception If this purchase option is not valid

     *            ESubscriptionPurchase then leave with

     *            KNcdErrorPurchaseOptionNotValidSubscriptionPurchase.

     *            Otherwise leave with System wide error code.

     */

    virtual const TDesC& ParentSubscriptionPurchaseOptionIdL() const = 0;

protected:

    /**

    * Destructor.

    *

    * @see MCatalogsBase::~MCatalogsBase

    */

    virtual ~MNcdPurchaseOption() {}

    };

#endif //  M_NCD_PURCHASE_OPTION_H