/*
* 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:   Declaration of MCatalogsEngine
*
*/


#ifndef CATALOGS_ENGINE_H
#define CATALOGS_ENGINE_H

#include <e32base.h>

#include "catalogsbase.h"

class MCatalogsEngineObserver;
class CCatalogsShutdown;

/**
 *  An interface providing the main handle to Catalogs engine
 *
 *  This class offers functionality for provider creation
 *
 *  
 */
class MCatalogsEngine : public virtual MCatalogsBase
    {

public:


    /**
     * Unique identifier for the interface, required for all MCatalogsBase interfaces.
     *
     * 
     */
    enum { KInterfaceUid = ECatalogsEngineUid };


    /**
     * Connect to the Catalogs engine. Content and services provided by
     * the engine depend on the client application's UID given as a parameter.
     * 
     * @note Once opened, the connection must be closed with MCatalogsEngine::Close()
     *  before the engine object can be released. Panic
     *  ECatalogsPanicSessionNotClosed will be raised if the connection is still
     *  open when the engine object is released.
     *
     * 
     * @param aClientUid Client identifier, used for content access control.
     * @return System wide error code.
     * @see MCatalogsEngine::Close
     */
    virtual TInt Connect( TUid aClientUid ) = 0;


    /**
     * Close connection to the Catalogs engine.
     *
     * @note All references to Catalogs Engine objects must be released before closing
     *  the session.
     *
     * 
     * @see MCatalogsEngine::Connect
     * @exception ECatalogsPanicUnreleasedReferencesExist Raised if unreleased references
     *  still exist to objects within the Catalogs Engine.
     */
    virtual void Close() = 0;


    /**
     * Requests a provider from the Catalogs engine. Specific provider
     * implementations are identified by UIDs.
     * Currently only one provider is supported:
     * NCD provider (uid=0x20008013)
     *
     * 
     * @param aUid Unique identifier of the provider that should be created.
     * @param aProvider Set to point to the newly created provider object. Counted, Release()
     *  must be called after use.
     * @param aStatus Status variable used to notify the completion of provider creation.
     * @param aProviderOptions Provider spesific options
     * @see MNcdProvider
     * @see ncdprovideroptions.h
     * @exception Leave System wide error code.
     * @see ncderrors.h For possible provider creation complition codes other
     * than KErrNone
     *
     * @note NCD provider uses Download manager in master mode with the connecting client's
     * SID. This prevents the client from using Download manager with it's own SID in
     * master mode. If the client needs to use Download manager in master mode, it must
     * connect to it with some other UID than its own SID.
     * 
     * @note aProviderOptions has effect only during the first CreateProviderL call
     * so if the client calls CreateProviderL twice during its execution, the
     * provider will be unaffected by the second call.
     */    
    virtual void CreateProviderL( 
        TInt aUid, 
        MCatalogsBase*& aProvider, 
        TRequestStatus& aStatus, 
        TUint32 aProviderOptions ) = 0;

    /**
     * Cancels provider creation.
     *
     * @note Completes the ongoing provider creation immediately
     *       with KErrCancel.
     *
     * 
     */
    virtual void CancelProviderCreation() = 0;


protected:

    /**
     * Destructor.
     *
     * @see MCatalogsBase::~MCatalogsBase
     */
    virtual ~MCatalogsEngine() {}

    };


/**
 *  A factory interface class for creating an instance of Catalogs Engine API.
 *
 *  @lib ncdengine_20019119.lib
 *  
 */
class CCatalogsEngine : public CBase, public MCatalogsEngine
    {

public:

#ifndef CATALOGS_ECOM

    /**
     * Catalogs Engine state.
     *
     * 
     */
    enum TState
        {
        /** Normal state, engine object instantiation allowed */
        EStateNormal,

        /** 
         * Going to maintenance mode. Engine instantiation not allowed, but
         * instances still exist.
         */
        EStatePrepareMaintenance,

        /** 
         * Maintenance mode. No Catalogs Engine instances exist, new ones
         * not allowed.
         */
        EStateMaintenance

        };

    /**
     * Returns the Catalogs Engine state.
     *
     * @return Catalogs Engine state.
     */
    IMPORT_C static TState StateL();


    /**
     * Instantiates the catalogs engine.
     *
     * @param aObserver Observer interface for the Catalogs Engine.
     * @return CCatalogsEngine* The instantiated object.
     */
    IMPORT_C static CCatalogsEngine* NewL( MCatalogsEngineObserver& aObserver );


    /**
     * Instantiates the catalogs engine, leaves pointer on cleanup stack.
     *
     * @param aObserver Observer interface for the Catalogs Engine.
     * @return CCatalogsEngine* The instantiated object.
     */
    IMPORT_C static CCatalogsEngine* NewLC( MCatalogsEngineObserver& aObserver );


    /**
     * Starts engine maintenance. All clients with open references to the engine will
     * receive a callback (MCatalogsEngineObserver::CatalogsEngineShutdown()) requesting
     * release of engine objects. Also, further engine instantiations are refused for
     * other clients until EndMaintenanceL() is called by the client that initiated the
     * update in the first place.
     *
     * @note The client calling StartMaintenanceL() may itself receive a callback for engine
     *  shutdown if it has open references to the Catalogs Engine. In this case, the client
     *  must obey the callback, like all other clients, and release the references.
     *
     * @note Reaching maintenance state can be observed by polling engine state with State().
     *
     * @exception KCatalogsErrorMaintenanceNotAuthorized Client is not authorized to
     *  start maintenance on engine.
     * @exception Leave System wide error code.
     */
    IMPORT_C static void StartMaintenanceL();


    /**
     * Ends engine maintenance. Engine usage is allowed.
     *
     * @exception KCatalogsErrorMaintenanceNotStarted Client has not started maintenance.
     * @exception Leave System wide error code.
     */
    IMPORT_C static void EndMaintenanceL();

#endif // CATALOGS_ECOM

    /**
     * Destructor.
     */
    virtual ~CCatalogsEngine();

protected:

    /**
     * Default constructor
     */
    CCatalogsEngine();

private:

    // Unique instance identifier key for ECom.                    
    TUid iDtor_ID_Key;

    };

#endif // CATALOGS_ENGINE_H