1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Declaration of MCatalogsEngine

    15 *

    16 */

    17 

    18 

    19 #ifndef CATALOGS_ENGINE_H

    20 #define CATALOGS_ENGINE_H

    21 

    22 #include <e32base.h>

    23 

    24 #include "catalogsbase.h"

    25 

    26 class MCatalogsEngineObserver;

    27 class CCatalogsShutdown;

    28 

    29 /**

    30  *  An interface providing the main handle to Catalogs engine

    31  *

    32  *  This class offers functionality for provider creation

    33  *

    34  *  

    35  */

    36 class MCatalogsEngine : public virtual MCatalogsBase

    37     {

    38 

    39 public:

    40 

    41 

    42     /**

    43      * Unique identifier for the interface, required for all MCatalogsBase interfaces.

    44      *

    45      * 

    46      */

    47     enum { KInterfaceUid = ECatalogsEngineUid };

    48 

    49 

    50     /**

    51      * Connect to the Catalogs engine. Content and services provided by

    52      * the engine depend on the client application's UID given as a parameter.

    53      * 

    54      * @note Once opened, the connection must be closed with MCatalogsEngine::Close()

    55      *  before the engine object can be released. Panic

    56      *  ECatalogsPanicSessionNotClosed will be raised if the connection is still

    57      *  open when the engine object is released.

    58      *

    59      * 

    60      * @param aClientUid Client identifier, used for content access control.

    61      * @return System wide error code.

    62      * @see MCatalogsEngine::Close

    63      */

    64     virtual TInt Connect( TUid aClientUid ) = 0;

    65 

    66 

    67     /**

    68      * Close connection to the Catalogs engine.

    69      *

    70      * @note All references to Catalogs Engine objects must be released before closing

    71      *  the session.

    72      *

    73      * 

    74      * @see MCatalogsEngine::Connect

    75      * @exception ECatalogsPanicUnreleasedReferencesExist Raised if unreleased references

    76      *  still exist to objects within the Catalogs Engine.

    77      */

    78     virtual void Close() = 0;

    79 

    80 

    81     /**

    82      * Requests a provider from the Catalogs engine. Specific provider

    83      * implementations are identified by UIDs.

    84      * Currently only one provider is supported:

    85      * NCD provider (uid=0x20008013)

    86      *

    87      * 

    88      * @param aUid Unique identifier of the provider that should be created.

    89      * @param aProvider Set to point to the newly created provider object. Counted, Release()

    90      *  must be called after use.

    91      * @param aStatus Status variable used to notify the completion of provider creation.

    92      * @param aProviderOptions Provider spesific options

    93      * @see MNcdProvider

    94      * @see ncdprovideroptions.h

    95      * @exception Leave System wide error code.

    96      * @see ncderrors.h For possible provider creation complition codes other

    97      * than KErrNone

    98      *

    99      * @note NCD provider uses Download manager in master mode with the connecting client's

   100      * SID. This prevents the client from using Download manager with it's own SID in

   101      * master mode. If the client needs to use Download manager in master mode, it must

   102      * connect to it with some other UID than its own SID.

   103      * 

   104      * @note aProviderOptions has effect only during the first CreateProviderL call

   105      * so if the client calls CreateProviderL twice during its execution, the

   106      * provider will be unaffected by the second call.

   107      */    

   108     virtual void CreateProviderL( 

   109         TInt aUid, 

   110         MCatalogsBase*& aProvider, 

   111         TRequestStatus& aStatus, 

   112         TUint32 aProviderOptions ) = 0;

   113 

   114     /**

   115      * Cancels provider creation.

   116      *

   117      * @note Completes the ongoing provider creation immediately

   118      *       with KErrCancel.

   119      *

   120      * 

   121      */

   122     virtual void CancelProviderCreation() = 0;

   123 

   124 

   125 protected:

   126 

   127     /**

   128      * Destructor.

   129      *

   130      * @see MCatalogsBase::~MCatalogsBase

   131      */

   132     virtual ~MCatalogsEngine() {}

   133 

   134     };

   135 

   136 

   137 /**

   138  *  A factory interface class for creating an instance of Catalogs Engine API.

   139  *

   140  *  @lib ncdengine_20019119.lib

   141  *  

   142  */

   143 class CCatalogsEngine : public CBase, public MCatalogsEngine

   144     {

   145 

   146 public:

   147 

   148 #ifndef CATALOGS_ECOM

   149 

   150     /**

   151      * Catalogs Engine state.

   152      *

   153      * 

   154      */

   155     enum TState

   156         {

   157         /** Normal state, engine object instantiation allowed */

   158         EStateNormal,

   159 

   160         /** 

   161          * Going to maintenance mode. Engine instantiation not allowed, but

   162          * instances still exist.

   163          */

   164         EStatePrepareMaintenance,

   165 

   166         /** 

   167          * Maintenance mode. No Catalogs Engine instances exist, new ones

   168          * not allowed.

   169          */

   170         EStateMaintenance

   171 

   172         };

   173 

   174     /**

   175      * Returns the Catalogs Engine state.

   176      *

   177      * @return Catalogs Engine state.

   178      */

   179     IMPORT_C static TState StateL();

   180 

   181 

   182     /**

   183      * Instantiates the catalogs engine.

   184      *

   185      * @param aObserver Observer interface for the Catalogs Engine.

   186      * @return CCatalogsEngine* The instantiated object.

   187      */

   188     IMPORT_C static CCatalogsEngine* NewL( MCatalogsEngineObserver& aObserver );

   189 

   190 

   191     /**

   192      * Instantiates the catalogs engine, leaves pointer on cleanup stack.

   193      *

   194      * @param aObserver Observer interface for the Catalogs Engine.

   195      * @return CCatalogsEngine* The instantiated object.

   196      */

   197     IMPORT_C static CCatalogsEngine* NewLC( MCatalogsEngineObserver& aObserver );

   198 

   199 

   200     /**

   201      * Starts engine maintenance. All clients with open references to the engine will

   202      * receive a callback (MCatalogsEngineObserver::CatalogsEngineShutdown()) requesting

   203      * release of engine objects. Also, further engine instantiations are refused for

   204      * other clients until EndMaintenanceL() is called by the client that initiated the

   205      * update in the first place.

   206      *

   207      * @note The client calling StartMaintenanceL() may itself receive a callback for engine

   208      *  shutdown if it has open references to the Catalogs Engine. In this case, the client

   209      *  must obey the callback, like all other clients, and release the references.

   210      *

   211      * @note Reaching maintenance state can be observed by polling engine state with State().

   212      *

   213      * @exception KCatalogsErrorMaintenanceNotAuthorized Client is not authorized to

   214      *  start maintenance on engine.

   215      * @exception Leave System wide error code.

   216      */

   217     IMPORT_C static void StartMaintenanceL();

   218 

   219 

   220     /**

   221      * Ends engine maintenance. Engine usage is allowed.

   222      *

   223      * @exception KCatalogsErrorMaintenanceNotStarted Client has not started maintenance.

   224      * @exception Leave System wide error code.

   225      */

   226     IMPORT_C static void EndMaintenanceL();

   227 

   228 #endif // CATALOGS_ECOM

   229 

   230     /**

   231      * Destructor.

   232      */

   233     virtual ~CCatalogsEngine();

   234 

   235 protected:

   236 

   237     /**

   238      * Default constructor

   239      */

   240     CCatalogsEngine();

   241 

   242 private:

   243 

   244     // Unique instance identifier key for ECom.                    

   245     TUid iDtor_ID_Key;

   246 

   247     };

   248 

   249 #endif // CATALOGS_ENGINE_H