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