diff -r 000000000000 -r ba25891c3a9e ncdengine/inc/catalogsengine.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/ncdengine/inc/catalogsengine.h	Thu Dec 17 08:51:10 2009 +0200
@@ -0,0 +1,249 @@
+/*
+* 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