1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Definition of MNcdSubscription interface

    15 *

    16 */

    17 

    18 

    19 #ifndef M_NCDSUBSCRIPTION_H

    20 #define M_NCDSUBSCRIPTION_H

    21 

    22 #include "catalogsbase.h"

    23 #include "ncdinterfaceids.h"

    24 

    25 class MNcdSubscriptionOperation;

    26 class MNcdSubscriptionOperationObserver;

    27 class TTime;

    28 class MNcdNode;

    29 

    30 /**

    31  *  Subscription interface.

    32  *

    33  *  This interface describes a subscription and provides methods for

    34  *  subscription management.

    35  *

    36  *  

    37  */

    38 class MNcdSubscription : public virtual MCatalogsBase

    39     {

    40     

    41 public:

    42 

    43     /**

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

    45      *

    46      * 

    47      */

    48     enum { KInterfaceUid = ENcdSubscriptionUid };

    49 

    50     

    51     /**

    52      * Type of the subscription renewal method.

    53      *

    54      */

    55     enum TType

    56         {

    57         

    58         /** Requires an explicit renewal after expiration. */

    59         EPeriodic,

    60 

    61         /** Renewed automatically on server side after expiration. */

    62         EAutomaticContinous

    63         };

    64 

    65     /**

    66      * Status of the subscription.

    67      *

    68      * 

    69      */

    70     enum TStatus

    71         {

    72 

    73         /**

    74          * Subscription has been purchased and is still active

    75          * (validity time/credits/downloads left).

    76          */

    77         ESubscriptionActive,

    78 

    79         /**

    80          * Subscription has been purchased, but has expired

    81          * (out of validity time/credits/downloads).

    82          */

    83         ESubscriptionExpired

    84         };

    85 

    86     /**

    87      * Name getter.

    88      *

    89      * 

    90      * @return Name of the subscription.

    91      */ 

    92     virtual const TDesC& Name() const = 0;

    93 

    94     /**

    95      * Icon getter.

    96      *

    97      * 

    98      * @return Icon data. Ownership is transferred. Empty descriptor

    99      *         returned if icon data is not set.

   100      * @exception Leave with KNcdErrorObsolete if this subscription

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

   102      */

   103     virtual HBufC8* IconL() const = 0;

   104 

   105     /**

   106      * Returns the current status for the subscription.

   107      *

   108      * 

   109      * @return Current status of the subscription.

   110      */

   111     virtual TStatus SubscriptionStatus() const = 0;

   112 

   113     /**

   114      * Checks whether this subscription is obsolete or not.

   115      * Subscription becomes obsolete if it is removed while

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

   117      * example because the subscription was removed from the

   118      * server.

   119      * Obsolete subscription should not be used and valid subscription

   120      * instances should be retrieved by using SubscriptionsL

   121      * method from MNcdSubscriptionManager interface.

   122      *

   123      * 

   124      * @return ETrue if this purchase option is obsolete.

   125      */

   126     virtual TBool IsObsolete() const = 0;

   127 

   128     /**

   129      * Returns whether the subscription has been unsubscribed or not.

   130      *

   131      * 

   132      * @return ETrue, if subscription has been unsubscribed. EFalse, if the subcription

   133      *  has not been unsubscribed.

   134      */

   135     virtual TBool Unsubscribed() const = 0;

   136 

   137     /**

   138      * Unsubscribe a currently valid subscription. 

   139      *

   140      * 

   141      * @param aObserver Operation observer interface.

   142      * @return Subscription operation object. Counted, Release() must be called after use.

   143      * @exception Leave with KNcdErrorObsolete if this subscription

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

   145      */

   146     virtual MNcdSubscriptionOperation* UnsubscribeL( 

   147         MNcdSubscriptionOperationObserver& aObserver ) = 0;

   148     

   149 

   150     /**

   151      * Get type of the subscription.

   152      *

   153      * 

   154      * @return Subscription type.

   155      */

   156     virtual TType SubscriptionType() const = 0;

   157     

   158 

   159     /**

   160      * Get subscription validity time information.

   161      *

   162      * 

   163      * @param aValidUntil Set to time when the subscription expires, if

   164      *  ETrue is returned, otherwise not used. Time given is in local time.

   165      * @return ETrue, if validity time is set. EFalse, if the subcription

   166      *  has no validity time limit set (stays valid indefinitely).

   167      */

   168     virtual TBool ValidityTime( TTime& aValidUntil ) const = 0;

   169 

   170 

   171     /**

   172      * Get subscription credit limit information.

   173      *

   174      * 

   175      * @param aCreditsLeft If ETrue is returned, set to current number of

   176      *  credits left in the subscription.

   177      * @param aTotalCredits If ETrue is returned, set to total number of

   178      *  credits the subscription originally had after purchase.

   179      * @return ETrue if subscription has a credit limit, EFalse otherwise.

   180      */

   181     virtual TBool CreditLimit( TReal& aCreditsLeft, TReal& aTotalCredits ) const = 0;

   182 

   183 

   184     /**

   185      * Get subscription download limit information.

   186      *

   187      * 

   188      * @param aDownloadsLeft If ETrue is returned, set to current number of

   189      *  downloads left in the subscription.

   190      * @param aTotalDownloads If ETrue is returned, set to total number of

   191      *  downloads the subscription originally had after purchase.

   192      * @return ETrue if subscription has a download limit, EFalse otherwise.

   193      */

   194     virtual TBool DownloadLimit( TInt& aDownloadsLeft, TInt& aTotalDownloads) const = 0;

   195 

   196 

   197     /**

   198      * Returns the node that has the purchase option which was used

   199      * to buy this subscription.

   200      *

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

   202      *         this subscription. Note that the node may be in an 

   203      *         uninitialized state, or in an initialized state, depending

   204      *         on whether the node has previously been known to the engine.

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

   206      *

   207      * @exception Leave with KNcdErrorObsolete if this subscription

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

   209      */

   210     virtual MNcdNode* OriginNodeL() const = 0;

   211 

   212     /**

   213      * Returns an id that identifies the purchaseoption that was used to buy

   214      * this subscription. Node that has the purchase option identified by

   215      * the id returned from this function can be queried by using method

   216      * OriginNodeL() of this class.

   217      *

   218      * @return Id that identifies the purchaseoption that was used

   219      *         to buy this subscription. Node where from this purchase

   220      *         option is found can be queried by using method

   221      *         OriginNodeL() of this class. Returns KNullDesC on error

   222      *         situations.

   223      */

   224     virtual const TDesC& OriginPurchaseOptionId() const = 0;

   225 

   226 

   227 

   228 protected: // Destruction

   229 

   230     /**

   231      * Destructor

   232      * 

   233      * Protected so that the implementing object cannot be deleted through

   234      * this interface by using delete. The destructor of an interface should

   235      * be set virtual to make sure that the destructors of derived classes

   236      * will be called when object is destroyed.

   237      */

   238     virtual ~MNcdSubscription() {}

   239 

   240     };

   241 

   242 #endif // M_NCDSUBSCRIPTION_H