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:   Contains MNcdProvider interface

    15 *

    16 */

    17 

    18 

    19 #ifndef M_NCD_PROVIDER_H

    20 #define M_NCD_PROVIDER_H

    21 

    22 

    23 #include <e32cmn.h>

    24 #include "catalogsbase.h"

    25 #include "catalogsarray.h"

    26 #include "ncdinterfaceids.h"

    27 #include "ncdschemenodetype.h"

    28 

    29 class MNcdNode;

    30 class MNcdNodeContainer;

    31 class MNcdProviderObserver;

    32 class MNcdOperation;

    33 class CNcdKeyValuePair;

    34 class MNcdPurchaseHistory;

    35 class MNcdSubscriptionManager;

    36 class MNcdKeyValuePair;

    37 class MNcdClientLocalizer;

    38 class MNcdFileDownloadOperation;

    39 class MNcdFileDownloadOperationObserver;

    40 class MNcdPurchaseDetails;

    41 class TNcdConnectionMethod;

    42 

    43 /**

    44  *  MNcdProvider provides functions to NCD specific functionality, such as

    45  *  purchase history access, subscription management, search, observing major

    46  *  events etc.

    47  *

    48  *  

    49  */

    50 class MNcdProvider : public virtual MCatalogsBase

    51 

    52     {

    53 public:

    54 

    55 

    56     /**

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

    58      *

    59      * 

    60      */

    61     enum { KInterfaceUid = ENcdProviderUid };        

    62 

    63 

    64     /**

    65      * Set the provider observer interface.

    66      *

    67      * @note NCD provider client should always set an observer to get callbacks.

    68      *

    69      * 

    70      * @param aObserver Observer interface to receive NCD provider callbacks. If NULL,

    71      *  no callbacks will be made.

    72      */

    73     virtual void SetObserver( MNcdProviderObserver* aObserver ) = 0;

    74 

    75 

    76     /**

    77      * Returns the root node for the provider. Root node provides access to

    78      * node hierarchy.

    79      *

    80      * 

    81      * @return Pointer to root node object. Counted, Release() must be

    82      *  called after use.

    83      * @exception Leave System wide error code.

    84      */

    85     virtual MNcdNode* RootNodeL() = 0;

    86 

    87 

    88     /**

    89      * Returns a list of currently active operations for progress monitoring and

    90      * operation management.

    91      * The returned operation objects have their reference counts incremented, the

    92      * items must be released after use e.g. with a call to the array's ResetAndDestroy().

    93      *

    94      * @note Lifetime of the operation objects cannot exceed the lifetime of the

    95      *  provider object. If there are unreleased references to a provider's operation

    96      *  objects when the last reference to the provider object is released, a panic

    97      *  will be raised.

    98      *

    99      * 

   100      * @return List of operation object pointers.

   101      * @exception Leave System wide error code.

   102      * @see MNcdOperation

   103      */

   104     virtual RCatalogsArray< MNcdOperation > OperationsL() const = 0;

   105 

   106 

   107     /**

   108      * Returns a handle to purchase history. Purchased, downloaded and installed

   109      * content can be accessed via the purchase history.

   110      *

   111      * 

   112      * @return Pointer to purchase history object. Counted, Release() must be called

   113      *  after use.

   114      * @exception Leave System wide error code.

   115      */

   116     virtual MNcdPurchaseHistory* PurchaseHistoryL() const = 0;

   117 

   118 

   119     /**

   120      * Returns a pointer to subscription manager object.

   121      *

   122      * 

   123      * @return Pointer to subscription manager. Counted, Release() must be called

   124      *  after use.

   125      * @exception Leave System wide error code.

   126      */

   127     virtual MNcdSubscriptionManager* SubscriptionsL() const = 0;

   128 

   129 

   130     /**

   131      * Adds a configuration that will be sent to content providers.

   132      *

   133      * Only one value per key is accepted. If the key already exists, it's old value

   134      * is replaced with the new one. The only exception are keys that match 

   135      * NcdConfigurationKeys::KCapability. The number of capability keys is not limited,

   136      * but their (folded) values are ensured to be unique.

   137      *

   138      * 

   139      * @param aConfiguration Configuration to be added.

   140      * @see MNcdProvider::RemoveConfigurationL

   141      * @see NcdConfigurationKeys

   142      * @exception Leave System wide error code.

   143      */

   144     virtual void AddConfigurationL( const MNcdKeyValuePair& aConfiguration ) = 0;

   145 

   146 

   147     /**

   148      * Removes a configuration. This configuration will no longer be sent to 

   149      * content providers.

   150      *

   151      * 

   152      * @param aKey Key of the configuration to be removed.

   153      * @exception KErrNotFound The configuration is not present.

   154      * @exception KErrAccessDenied The configuration has been added by the root-node

   155      *            provider and can not be removed by the user.

   156      * @see MNcdProvider::AddConfigurationL

   157      */

   158     virtual void RemoveConfigurationL( const TDesC& aKey ) = 0;

   159 

   160 

   161     /**

   162      * Returns a list of configurations that are used when communicating with

   163      * content providers. 

   164      *

   165      * 

   166      * @return Current configuration as an array of key-value pairs. Ownership

   167      *  of the objects within the array is transferred to the caller, they must

   168      *  be deleted after use e.g. calling RPointerArray::ResetAndDestroy().

   169      * @see MNcdProvider::AddConfigurationL

   170      * @see MNcdProvider::RemoveConfigurationL

   171      * @exception KErrNotFound if no configurations have been set

   172      * @exception Leave System wide error code.

   173      */

   174     virtual RPointerArray< CNcdKeyValuePair > ConfigurationsL() const = 0;

   175 

   176 

   177     /**

   178      * Retrieves a node identified by a namespace Id and a node Id.

   179      *

   180      * 

   181      * @param aNameSpaceId  Namespace of the requested node. Node Ids are unique

   182      *                      inside a specific namespace.

   183      * @param aNodeId       Id of the requested node.

   184      *

   185      * @return Pointer to the requested node object. Note, that the node may be

   186      *  in an uninitialized state, or in an initialized state, depending on

   187      *  whether all the required node information has previously been loaded 

   188      *  from the server.

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

   190      * @exception Leave KErrNotFound if the node is not found from the RAM or database

   191      *  cache.

   192      * @exception Leave System wide error code.

   193      */

   194     virtual MNcdNode* NodeL( const TDesC& aNameSpaceId, 

   195                              const TDesC& aNodeId ) const = 0;

   196 

   197 

   198     /**

   199      * Retrieves a node identified by purchase history details

   200      *

   201      * 

   202      * @param aDetails  Purchase details

   203      *

   204      * @return Pointer to the requested node object. Note, that the returned node

   205      *  is not located in the normal browsing hierarchy but it is just hanging by

   206      *  itself as a temporary node. If the metadata that corresponds the purchase details 

   207      *  is found from the RAM or database cache, that metadata will be used for the node. 

   208      *  If the metadata can not be found, then it will be initialized with the values 

   209      *  provided by the corresponding purchase details.

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

   211      * @exception Leave System wide error code.

   212      */

   213     virtual MNcdNode* NodeL( const MNcdPurchaseDetails& aDetails ) const = 0;

   214 

   215     /**

   216      * Retrieves a scheme node identified by a namespace Id, a node metadata Id and

   217      * a server URI. If the scheme node is created, it will not have any parent. The scheme

   218      * node is automatically set as favourite node.

   219      *

   220      * 

   221      * @param aNameSpaceId  Namespace of the requested node. Node Ids are unique

   222      *                      inside a specific namespace.

   223      * @param aEntityId     Id of the requested node metadata.

   224      * @param aServerUri    Server URI of the requested node.

   225      * @param aType         Type of the scheme node.

   226      * @param aRemoveOnDisconnect If ETrue, the scheme node is removed from favourites when

   227      *                      the client-server session is closed.

   228      * @param aForceCreate  ETrue means that, if necessary, a scheme node will always 

   229      *                      be created. Notice, that an uninitialized node object will be 

   230      *                      returned for an invalid name space or node metadata id.

   231      *                      EFalse means that the scheme node will be returned 

   232      *                      only if the node itself or the metadata for it already

   233      *                      existed in the RAM or database cache. 

   234      *

   235      * @return Pointer to the requested node object. Note, that the node may be

   236      *  in an uninitialized state, or in an initialized state, depending on

   237      *  whether the node has previously been known to the engine.

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

   239      * @exception Leave KErrNotFound if aForceCreate parameter has been set as EFalse 

   240      *  and the metadata is not found from the RAM or database cache.

   241      * @exception Leave KErrArgument if the metadata already exists but is of different

   242      *  type than the given scheme node type.

   243      * @exception Leave System wide error code.

   244      */

   245     virtual MNcdNode* SchemeNodeL( const TDesC& aNameSpaceId,

   246                                    const TDesC& aEntityId,

   247                                    const TDesC& aServerUri,

   248                                    TNcdSchemeNodeType aType,

   249                                    TBool aRemoveOnDisconnect,

   250                                    TBool aForceCreate ) const = 0;

   251 

   252     /**

   253      * Sets the client string localizer interface to be used for server-initiated

   254      * localizable string information.

   255      *

   256      * 

   257      * @param aLocalizer Localizer to be used for translating localization keys

   258      *  into user viewable strings.

   259      */

   260     virtual void SetStringLocalizer( MNcdClientLocalizer& aLocalizer ) = 0;

   261 

   262 

   263     /**

   264      * Downloads a file from the given URI. The file is not handled by the engine, 

   265      * the file should be handled by the user of this interface as it sees fit.

   266      *

   267      * @note The reference count of the operation object is increased by one. 

   268      * So, Release function of the operation should be called when the operation 

   269      * is not needed anymore.

   270      *

   271      * @note The file will be moved to the target location after it has been 

   272      * fully downloaded. Any existing file with the same name will be overwritten.

   273      *

   274      * 

   275      * @param aUri Source URI

   276      * @param aTargetFileName Full path and name for the target file.

   277      * @param aObserver

   278      */

   279     virtual MNcdFileDownloadOperation* DownloadFileL( const TDesC& aUri,

   280         const TDesC& aTargetFileName,

   281         MNcdFileDownloadOperationObserver& aObserver ) = 0;

   282         

   283 

   284     /**

   285      * Sets the default connection method used for network access.

   286      *

   287      * @note Not stored persistently. A client needs to set this again every time it

   288      *  creates the provider.

   289      *

   290      * 

   291      * @param aMethod Identifier of the connection method to use by default.

   292      */    

   293     virtual void SetDefaultConnectionMethodL( 

   294         const TNcdConnectionMethod& aMethod ) = 0;

   295     

   296     /**

   297      * Clears all search results. This method should be called before starting a new

   298      * search. 

   299      *

   300      * @note This method only marks the search result nodes for removal and makes them

   301      * unavailable, therefore it doesn't take a long time to complete. 

   302      * @note Previous result nodes need to be released to remove them from cache.

   303      */

   304     virtual void ClearSearchResultsL() = 0;

   305     

   306     

   307     /**

   308      * Clears the entire client cache (nodes, icons, previews)

   309      *

   310      * @note The client should release all nodes and close all open files before 

   311      * calling this method.

   312      */

   313     virtual void ClearCacheL( TRequestStatus& aStatus ) = 0;

   314     

   315     

   316     /**

   317      * Tells whether the SIM was changed or removed since the previous startup.

   318      *

   319      * @return ETrue If the SIM was changed or removed, otherwise EFalse.

   320      */

   321     virtual TBool IsSimChangedL() = 0;

   322     

   323     

   324     /**

   325      * Tells whether fixed access point defined in engine's configuration file is used.

   326      * In this case AP selection possibility may need to be disabled in UI.

   327      *

   328      * @return ETrue If fixed AP is used, otherwise EFalse.

   329      * @leave System wide error code.

   330      */

   331     virtual TBool IsFixedApL() = 0;

   332 

   333 protected:

   334 

   335     /**

   336      * Destructor.

   337      *

   338      * @see MCatalogsBase::~MCatalogsBase

   339      */

   340     virtual ~MNcdProvider() {}

   341 

   342     };

   343 

   344 

   345 #endif // M_NCD_PROVIDER_H