/*

* 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