/*
* 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