--- /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 <e32cmn.h>
+#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