/*

* 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