/*
* 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:   Definition of MNcdSubscription interface
*
*/


#ifndef M_NCDSUBSCRIPTION_H
#define M_NCDSUBSCRIPTION_H

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

class MNcdSubscriptionOperation;
class MNcdSubscriptionOperationObserver;
class TTime;
class MNcdNode;

/**
 *  Subscription interface.
 *
 *  This interface describes a subscription and provides methods for
 *  subscription management.
 *
 *  
 */
class MNcdSubscription : public virtual MCatalogsBase
    {
    
public:

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

    
    /**
     * Type of the subscription renewal method.
     *
     */
    enum TType
        {
        
        /** Requires an explicit renewal after expiration. */
        EPeriodic,

        /** Renewed automatically on server side after expiration. */
        EAutomaticContinous
        };

    /**
     * Status of the subscription.
     *
     * 
     */
    enum TStatus
        {

        /**
         * Subscription has been purchased and is still active
         * (validity time/credits/downloads left).
         */
        ESubscriptionActive,

        /**
         * Subscription has been purchased, but has expired
         * (out of validity time/credits/downloads).
         */
        ESubscriptionExpired
        };

    /**
     * Name getter.
     *
     * 
     * @return Name of the subscription.
     */ 
    virtual const TDesC& Name() const = 0;

    /**
     * Icon getter.
     *
     * 
     * @return Icon data. Ownership is transferred. Empty descriptor
     *         returned if icon data is not set.
     * @exception Leave with KNcdErrorObsolete if this subscription
     *            is obsolete. Otherwise leave with System wide error code.
     */
    virtual HBufC8* IconL() const = 0;

    /**
     * Returns the current status for the subscription.
     *
     * 
     * @return Current status of the subscription.
     */
    virtual TStatus SubscriptionStatus() const = 0;

    /**
     * Checks whether this subscription is obsolete or not.
     * Subscription becomes obsolete if it is removed while
     * user still has reference to it. Removal can be done for
     * example because the subscription was removed from the
     * server.
     * Obsolete subscription should not be used and valid subscription
     * instances should be retrieved by using SubscriptionsL
     * method from MNcdSubscriptionManager interface.
     *
     * 
     * @return ETrue if this purchase option is obsolete.
     */
    virtual TBool IsObsolete() const = 0;

    /**
     * Returns whether the subscription has been unsubscribed or not.
     *
     * 
     * @return ETrue, if subscription has been unsubscribed. EFalse, if the subcription
     *  has not been unsubscribed.
     */
    virtual TBool Unsubscribed() const = 0;

    /**
     * Unsubscribe a currently valid subscription. 
     *
     * 
     * @param aObserver Operation observer interface.
     * @return Subscription operation object. Counted, Release() must be called after use.
     * @exception Leave with KNcdErrorObsolete if this subscription
     *            is obsolete. Otherwise leave with System wide error code.
     */
    virtual MNcdSubscriptionOperation* UnsubscribeL( 
        MNcdSubscriptionOperationObserver& aObserver ) = 0;
    

    /**
     * Get type of the subscription.
     *
     * 
     * @return Subscription type.
     */
    virtual TType SubscriptionType() const = 0;
    

    /**
     * Get subscription validity time information.
     *
     * 
     * @param aValidUntil Set to time when the subscription expires, if
     *  ETrue is returned, otherwise not used. Time given is in local time.
     * @return ETrue, if validity time is set. EFalse, if the subcription
     *  has no validity time limit set (stays valid indefinitely).
     */
    virtual TBool ValidityTime( TTime& aValidUntil ) const = 0;


    /**
     * Get subscription credit limit information.
     *
     * 
     * @param aCreditsLeft If ETrue is returned, set to current number of
     *  credits left in the subscription.
     * @param aTotalCredits If ETrue is returned, set to total number of
     *  credits the subscription originally had after purchase.
     * @return ETrue if subscription has a credit limit, EFalse otherwise.
     */
    virtual TBool CreditLimit( TReal& aCreditsLeft, TReal& aTotalCredits ) const = 0;


    /**
     * Get subscription download limit information.
     *
     * 
     * @param aDownloadsLeft If ETrue is returned, set to current number of
     *  downloads left in the subscription.
     * @param aTotalDownloads If ETrue is returned, set to total number of
     *  downloads the subscription originally had after purchase.
     * @return ETrue if subscription has a download limit, EFalse otherwise.
     */
    virtual TBool DownloadLimit( TInt& aDownloadsLeft, TInt& aTotalDownloads) const = 0;


    /**
     * Returns the node that has the purchase option which was used
     * to buy this subscription.
     *
     * @return Pointer to the node that has the purchase option to buy
     *         this subscription. 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 subscription
     *            is obsolete. Otherwise leave with System wide error code.
     */
    virtual MNcdNode* OriginNodeL() const = 0;

    /**
     * Returns an id that identifies the purchaseoption that was used to buy
     * this subscription. Node that has the purchase option identified by
     * the id returned from this function can be queried by using method
     * OriginNodeL() of this class.
     *
     * @return Id that identifies the purchaseoption that was used
     *         to buy this subscription. Node where from this purchase
     *         option is found can be queried by using method
     *         OriginNodeL() of this class. Returns KNullDesC on error
     *         situations.
     */
    virtual const TDesC& OriginPurchaseOptionId() const = 0;



protected: // Destruction

    /**
     * Destructor
     * 
     * Protected so that the implementing object cannot be deleted through
     * this interface by using delete. The destructor of an interface should
     * be set virtual to make sure that the destructors of derived classes
     * will be called when object is destroyed.
     */
    virtual ~MNcdSubscription() {}

    };

#endif // M_NCDSUBSCRIPTION_H