diff -r 000000000000 -r ba25891c3a9e ncdengine/inc/ncdprovider.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/ncdengine/inc/ncdprovider.h Thu Dec 17 08:51:10 2009 +0200 @@ -0,0 +1,345 @@ +/* +* 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: Contains MNcdProvider interface +* +*/ + + +#ifndef M_NCD_PROVIDER_H +#define M_NCD_PROVIDER_H + + +#include +#include "catalogsbase.h" +#include "catalogsarray.h" +#include "ncdinterfaceids.h" +#include "ncdschemenodetype.h" + +class MNcdNode; +class MNcdNodeContainer; +class MNcdProviderObserver; +class MNcdOperation; +class CNcdKeyValuePair; +class MNcdPurchaseHistory; +class MNcdSubscriptionManager; +class MNcdKeyValuePair; +class MNcdClientLocalizer; +class MNcdFileDownloadOperation; +class MNcdFileDownloadOperationObserver; +class MNcdPurchaseDetails; +class TNcdConnectionMethod; + +/** + * MNcdProvider provides functions to NCD specific functionality, such as + * purchase history access, subscription management, search, observing major + * events etc. + * + * + */ +class MNcdProvider : public virtual MCatalogsBase + + { +public: + + + /** + * Unique identifier for the interface, required for all MCatalogsBase interfaces. + * + * + */ + enum { KInterfaceUid = ENcdProviderUid }; + + + /** + * Set the provider observer interface. + * + * @note NCD provider client should always set an observer to get callbacks. + * + * + * @param aObserver Observer interface to receive NCD provider callbacks. If NULL, + * no callbacks will be made. + */ + virtual void SetObserver( MNcdProviderObserver* aObserver ) = 0; + + + /** + * Returns the root node for the provider. Root node provides access to + * node hierarchy. + * + * + * @return Pointer to root node object. Counted, Release() must be + * called after use. + * @exception Leave System wide error code. + */ + virtual MNcdNode* RootNodeL() = 0; + + + /** + * Returns a list of currently active operations for progress monitoring and + * operation management. + * The returned operation objects have their reference counts incremented, the + * items must be released after use e.g. with a call to the array's ResetAndDestroy(). + * + * @note Lifetime of the operation objects cannot exceed the lifetime of the + * provider object. If there are unreleased references to a provider's operation + * objects when the last reference to the provider object is released, a panic + * will be raised. + * + * + * @return List of operation object pointers. + * @exception Leave System wide error code. + * @see MNcdOperation + */ + virtual RCatalogsArray< MNcdOperation > OperationsL() const = 0; + + + /** + * Returns a handle to purchase history. Purchased, downloaded and installed + * content can be accessed via the purchase history. + * + * + * @return Pointer to purchase history object. Counted, Release() must be called + * after use. + * @exception Leave System wide error code. + */ + virtual MNcdPurchaseHistory* PurchaseHistoryL() const = 0; + + + /** + * Returns a pointer to subscription manager object. + * + * + * @return Pointer to subscription manager. Counted, Release() must be called + * after use. + * @exception Leave System wide error code. + */ + virtual MNcdSubscriptionManager* SubscriptionsL() const = 0; + + + /** + * Adds a configuration that will be sent to content providers. + * + * Only one value per key is accepted. If the key already exists, it's old value + * is replaced with the new one. The only exception are keys that match + * NcdConfigurationKeys::KCapability. The number of capability keys is not limited, + * but their (folded) values are ensured to be unique. + * + * + * @param aConfiguration Configuration to be added. + * @see MNcdProvider::RemoveConfigurationL + * @see NcdConfigurationKeys + * @exception Leave System wide error code. + */ + virtual void AddConfigurationL( const MNcdKeyValuePair& aConfiguration ) = 0; + + + /** + * Removes a configuration. This configuration will no longer be sent to + * content providers. + * + * + * @param aKey Key of the configuration to be removed. + * @exception KErrNotFound The configuration is not present. + * @exception KErrAccessDenied The configuration has been added by the root-node + * provider and can not be removed by the user. + * @see MNcdProvider::AddConfigurationL + */ + virtual void RemoveConfigurationL( const TDesC& aKey ) = 0; + + + /** + * Returns a list of configurations that are used when communicating with + * content providers. + * + * + * @return Current configuration as an array of key-value pairs. Ownership + * of the objects within the array is transferred to the caller, they must + * be deleted after use e.g. calling RPointerArray::ResetAndDestroy(). + * @see MNcdProvider::AddConfigurationL + * @see MNcdProvider::RemoveConfigurationL + * @exception KErrNotFound if no configurations have been set + * @exception Leave System wide error code. + */ + virtual RPointerArray< CNcdKeyValuePair > ConfigurationsL() const = 0; + + + /** + * Retrieves a node identified by a namespace Id and a node Id. + * + * + * @param aNameSpaceId Namespace of the requested node. Node Ids are unique + * inside a specific namespace. + * @param aNodeId Id of the requested node. + * + * @return Pointer to the requested node object. Note, that the node may be + * in an uninitialized state, or in an initialized state, depending on + * whether all the required node information has previously been loaded + * from the server. + * Counted, Release() must be called after use. + * @exception Leave KErrNotFound if the node is not found from the RAM or database + * cache. + * @exception Leave System wide error code. + */ + virtual MNcdNode* NodeL( const TDesC& aNameSpaceId, + const TDesC& aNodeId ) const = 0; + + + /** + * Retrieves a node identified by purchase history details + * + * + * @param aDetails Purchase details + * + * @return Pointer to the requested node object. Note, that the returned node + * is not located in the normal browsing hierarchy but it is just hanging by + * itself as a temporary node. If the metadata that corresponds the purchase details + * is found from the RAM or database cache, that metadata will be used for the node. + * If the metadata can not be found, then it will be initialized with the values + * provided by the corresponding purchase details. + * Counted, Release() must be called after use. + * @exception Leave System wide error code. + */ + virtual MNcdNode* NodeL( const MNcdPurchaseDetails& aDetails ) const = 0; + + /** + * Retrieves a scheme node identified by a namespace Id, a node metadata Id and + * a server URI. If the scheme node is created, it will not have any parent. The scheme + * node is automatically set as favourite node. + * + * + * @param aNameSpaceId Namespace of the requested node. Node Ids are unique + * inside a specific namespace. + * @param aEntityId Id of the requested node metadata. + * @param aServerUri Server URI of the requested node. + * @param aType Type of the scheme node. + * @param aRemoveOnDisconnect If ETrue, the scheme node is removed from favourites when + * the client-server session is closed. + * @param aForceCreate ETrue means that, if necessary, a scheme node will always + * be created. Notice, that an uninitialized node object will be + * returned for an invalid name space or node metadata id. + * EFalse means that the scheme node will be returned + * only if the node itself or the metadata for it already + * existed in the RAM or database cache. + * + * @return Pointer to the requested node object. 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 KErrNotFound if aForceCreate parameter has been set as EFalse + * and the metadata is not found from the RAM or database cache. + * @exception Leave KErrArgument if the metadata already exists but is of different + * type than the given scheme node type. + * @exception Leave System wide error code. + */ + virtual MNcdNode* SchemeNodeL( const TDesC& aNameSpaceId, + const TDesC& aEntityId, + const TDesC& aServerUri, + TNcdSchemeNodeType aType, + TBool aRemoveOnDisconnect, + TBool aForceCreate ) const = 0; + + /** + * Sets the client string localizer interface to be used for server-initiated + * localizable string information. + * + * + * @param aLocalizer Localizer to be used for translating localization keys + * into user viewable strings. + */ + virtual void SetStringLocalizer( MNcdClientLocalizer& aLocalizer ) = 0; + + + /** + * Downloads a file from the given URI. The file is not handled by the engine, + * the file should be handled by the user of this interface as it sees fit. + * + * @note The reference count of the operation object is increased by one. + * So, Release function of the operation should be called when the operation + * is not needed anymore. + * + * @note The file will be moved to the target location after it has been + * fully downloaded. Any existing file with the same name will be overwritten. + * + * + * @param aUri Source URI + * @param aTargetFileName Full path and name for the target file. + * @param aObserver + */ + virtual MNcdFileDownloadOperation* DownloadFileL( const TDesC& aUri, + const TDesC& aTargetFileName, + MNcdFileDownloadOperationObserver& aObserver ) = 0; + + + /** + * Sets the default connection method used for network access. + * + * @note Not stored persistently. A client needs to set this again every time it + * creates the provider. + * + * + * @param aMethod Identifier of the connection method to use by default. + */ + virtual void SetDefaultConnectionMethodL( + const TNcdConnectionMethod& aMethod ) = 0; + + /** + * Clears all search results. This method should be called before starting a new + * search. + * + * @note This method only marks the search result nodes for removal and makes them + * unavailable, therefore it doesn't take a long time to complete. + * @note Previous result nodes need to be released to remove them from cache. + */ + virtual void ClearSearchResultsL() = 0; + + + /** + * Clears the entire client cache (nodes, icons, previews) + * + * @note The client should release all nodes and close all open files before + * calling this method. + */ + virtual void ClearCacheL( TRequestStatus& aStatus ) = 0; + + + /** + * Tells whether the SIM was changed or removed since the previous startup. + * + * @return ETrue If the SIM was changed or removed, otherwise EFalse. + */ + virtual TBool IsSimChangedL() = 0; + + + /** + * Tells whether fixed access point defined in engine's configuration file is used. + * In this case AP selection possibility may need to be disabled in UI. + * + * @return ETrue If fixed AP is used, otherwise EFalse. + * @leave System wide error code. + */ + virtual TBool IsFixedApL() = 0; + +protected: + + /** + * Destructor. + * + * @see MCatalogsBase::~MCatalogsBase + */ + virtual ~MNcdProvider() {} + + }; + + +#endif // M_NCD_PROVIDER_H