1 /*

     2 * Copyright (c) 2002-2007 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: Handle to a local landmark database.

    15 *

    16 *

    17 */

    18 

    19 

    20 #ifndef CPOSLMLOCALDATABASE_H

    21 #define CPOSLMLOCALDATABASE_H

    22 

    23 #include <e32base.h>

    24 #include <epos_cposlandmarkdatabaseextended.h>

    25 #include <EPos_CPosLandmarkEncoder.h>

    26 #include <EPos_CPosLandmarkParser.h>

    27 #include <epos_cposlmdiskutilities.h>

    28 #include <epos_mposlmdatabasefastcounters.h>

    29 

    30 class CPosLmLocalDbAccess;

    31 class CPosLandmark;

    32 class RPosLandmarkServer;

    33 class RPosLmLocalNameIndex;

    34 class RPosLmLocalAccessSubsession;

    35 class CPosLmDiskUtilities;

    36 class CPosLmLocalImportOp;

    37 class CPosLmLocalCategoryManager;

    38 class CPosLmLocalDbFastCounters;

    39 

    40 /**

    41 * Handle to a local landmark database.

    42 *

    43 * This class contains functions for creating, iterating, reading, modifying

    44 * and deleting landmarks.

    45 *

    46 * @lib eposlmlocalaccess.lib

    47 */

    48 class CPosLmLocalDatabase : public CPosLandmarkDatabaseExtended

    49     {

    50 

    51     public: // Constructors and destructor

    52 

    53         /**

    54         * Two-phased constructor.

    55         *

    56         * Opens a local landmark database specified by the database URI.

    57         *

    58         * @param[in] aDatabaseURI Database URI here represented as a path in the

    59         *   filesystem. If the URI is NULL the default landmark database will

    60         *   be loaded. The TAny pointer must be a HBufC pointer (a cast will be

    61         *   made). This class is instantiated by the ECom framework.

    62         * @return A new instance of this class.

    63         */

    64         IMPORT_C static CPosLmLocalDatabase* OpenL( TAny* aDatabaseUri );

    65 

    66         /**

    67         * Destructor.

    68         */

    69         IMPORT_C ~CPosLmLocalDatabase();

    70 

    71     public:  // Data types

    72 

    73         /** Specifies the type of database lock. */

    74         enum TLockType

    75             {

    76             EUnlocked = 0,

    77             EReadLock,

    78             EWriteLock

    79             };

    80 

    81         /** Specifies the transaction operation */

    82         enum TTransactionOp

    83             {

    84             EStart,

    85             ECommit,

    86             ERollback

    87             };

    88 

    89     public: // New functions

    90 

    91         /**

    92         * Copies partial settings from aFromSetting to aToSetting.

    93         *

    94         * @param aFromSetting The source partial read parameter settings.

    95         * @param aToSetting The destination partial read parameter settings.

    96         */

    97         void CopyPartialSettingsL(

    98             const CPosLmPartialReadParameters& aFromSetting,

    99             CPosLmPartialReadParameters& aToSetting );

   100 

   101         /**

   102         * Returns a handle to a database access object.

   103         * @return A database access object.

   104         */

   105         IMPORT_C CPosLmLocalDbAccess* DatabaseAccess();

   106 

   107         /**

   108         * Leaves with KErrPosLmNotInitialized if initialization is needed.

   109         */

   110         IMPORT_C void LeaveIfInitializingIsNeededL();

   111 

   112         /**

   113         * Returns the drive unit for current database.

   114         * @return A drive unit character.

   115         */

   116         TChar DatabaseDrive();

   117 

   118         /**

   119         * Returs a handle to the Landmarks Server.

   120         * @return Handle to the server.

   121         */

   122         RPosLmLocalAccessSubsession& Session();

   123 

   124         /**

   125         * Registers an event in the Landmarks Server.

   126         * @param aEventType Type of event.

   127         * @param aId Optional landmarks id.

   128         * @return KErrNone if successful. Otherwise any system-wide error code.

   129         */

   130         TInt RegisterEvent(

   131             TPosLmEventType aEventType,

   132             TPosLmItemId aId = KPosLmNullItemId );

   133 

   134         /**

   135         * Sets a lock on the database and puts a release lock function on the

   136         * clean-up stack.

   137         *

   138         * Leaves with KErrLocked if the aquired lock is not compatible with

   139         * previous locks on the database.

   140         *

   141         * @param aLockType The type of lock to set.

   142         */

   143         IMPORT_C void AquireLockLC( TLockType aLockType );

   144 

   145         /**

   146         * Sets a lock on the database. Does not put a release lock function on

   147         * the clean-up stack. Useful for asynchronous operations.

   148         *

   149         * Leaves with KErrLocked if the aquired lock is not compatible with

   150         * previous locks on the database.

   151         * 

   152         * @param aLockType The type of lock to set.

   153         */

   154         IMPORT_C void AquireLockL( TLockType aLockType );

   155 

   156         /**

   157         * Releases a lock on the database. Useful for asynchronous operations

   158         * that cannot put a release lock function on the clean-up stack.

   159         * 

   160         * @param aLockType The type of lock to release.

   161         */

   162         IMPORT_C TInt ReleaseLock( TLockType aLockType );

   163         

   164         /**

   165         * Returs a handle to the Landmarks Server.

   166         * @return Handle to the server.

   167         */

   168         IMPORT_C RPosLmLocalNameIndex& NameIndex();

   169 

   170         /**

   171         * Returs a handle to the Landmarks Server.

   172         * @return Handle to the server.

   173         */

   174         IMPORT_C const RPosLmLocalNameIndex& NameIndex() const;

   175 

   176         /** Starts new transaction for server data. 

   177          *  Puts rollback action to cleanup stack.

   178          *  Used in landmark change transactions to ensure updating

   179          *  lm name index on server side */

   180         IMPORT_C void BeginServerTransactionLC();

   181         

   182         /** Starts new transaction for server data. 

   183          *  Used in landmark change transactions to ensure updating

   184          *  lm name index on server side */

   185         IMPORT_C void BeginServerTransactionL();

   186 

   187         /** Commits current server data transaction and removes rollback from cleanup */

   188         IMPORT_C void CommitServerTransactionLX();

   189         

   190         /** Commits current server data transaction */

   191         IMPORT_C void CommitServerTransactionL();

   192 

   193         /** Cancels current transaction */

   194         IMPORT_C void RollbackServerTransaction();

   195 

   196     public: // From CPosLandmarkDatabase.

   197 

   198         /** @returns @p ETrue if the database is in need of initialization,

   199         *   otherwise @p EFalse. */

   200         TBool IsInitializingNeeded() const;

   201 

   202         /** @returns A handle to the operation. */

   203         CPosLmOperation* InitializeL();

   204 

   205         /** @param aLandmarkId The ID of the landmark to read.

   206         *   @returns The requested landmark. The landmark object is put on the

   207         *   cleanup stack. */

   208         CPosLandmark* ReadLandmarkLC( TPosLmItemId aLandmarkId );

   209 

   210         /** @return The landmark iterator. */

   211         CPosLmItemIterator* LandmarkIteratorL();

   212 

   213         /** @param[in] aSortPref A sort preference object.

   214         *   @return The landmark iterator. */

   215         CPosLmItemIterator* LandmarkIteratorL( const TPosLmSortPref& aSortPref );

   216 

   217         /** @param[in,out] aLandmark The landmark to add.

   218         *   @return The ID of the new landmark. */

   219         TPosLmItemId AddLandmarkL( CPosLandmark& aLandmark );

   220 

   221         /** @param[in] aLandmark The new landmark data. */

   222         void UpdateLandmarkL( const CPosLandmark& aLandmark );

   223 

   224         /** @param aLandmarkId The ID of the landmark to remove.*/

   225         void RemoveLandmarkL( TPosLmItemId aLandmarkId );

   226 

   227         /** @param aLandmarkIdArray The IDs of the landmarks to remove.

   228         *   @returns A handle to the operation. */

   229         CPosLmOperation* RemoveLandmarksL(

   230             const RArray<TPosLmItemId>& aLandmarkIdArray );

   231 

   232         /** @returns A handle to the operation. */

   233         CPosLmOperation* RemoveAllLandmarksL();

   234 

   235         /** @returns The current partial read parameters. */

   236         CPosLmPartialReadParameters* PartialReadParametersLC();

   237 

   238         /** @param aPartialSettings The new partial read parameters. */

   239         void SetPartialReadParametersL(

   240             const CPosLmPartialReadParameters& aPartialSettings );

   241 

   242         /** @param The ID of the landmark to read.

   243         *   @returns The requested landmark. The landmark object will only

   244         *   contain the attributes defined in the partial read attributes. The

   245         *   landmark object is put on the cleanup stack. */

   246         CPosLandmark* ReadPartialLandmarkLC( TPosLmItemId aLandmarkId );

   247 

   248         /** @param aLandmarkIdArray An array with IDs of the landmarks to read.

   249         *   @returns A handle to the operation. */

   250         CPosLmOperation* PreparePartialLandmarksL(

   251             const RArray<TPosLmItemId>& aLandmarkIdArray );

   252 

   253         /** @param aPreparePartialLandmarkOperation The operation object returned

   254         *   by the @ref PreparePartialLandmarksL function.

   255         *   @returns An array containing the prepared partial landmark objects. */

   256         CArrayPtr<CPosLandmark>* TakePreparedPartialLandmarksL(

   257             CPosLmOperation* aPreparePartialLandmarkOperation );

   258 

   259         /** @returns The database URI. The URI is put on the cleanup stack. */

   260         HBufC* DatabaseUriLC();

   261 

   262         /** @returns Size information for the database. */

   263         TSize SizeL();

   264 

   265         /** @returns A handle to the operation. */

   266         CPosLmOperation* CompactL();

   267 

   268         /** @param[out] aEvent Will contain the event information when an event occurs.

   269         *   @param[out] aStatus Will be completed with @p KErrNone if an event

   270         *   occurs and an error code if some error was encountered. */

   271         void NotifyDatabaseEvent(

   272             TPosLmEvent& aEvent,

   273             TRequestStatus& aStatus );

   274 

   275         /** @return @p KErrNone if the request was successfully cancelled,

   276         *   otherwise a system wide error code. */

   277         TInt CancelNotifyDatabaseEvent();

   278 

   279         /** @param[in] aLandmarkEncoder A landmark encoder object.

   280         *   @param[in] aLandmarkIdArray The landmarks which should be exported.

   281         *   @param[in] aTransferOptions A bitmap representing the options for the

   282         *   export operation. The bitmap values are defined by

   283         *   @ref _TTransferOptions.

   284         *   @returns A handle to the operation. */

   285         CPosLmOperation* ExportLandmarksL(

   286             CPosLandmarkEncoder&  aLandmarkEncoder,

   287             const RArray<TPosLmItemId>&  aLandmarkIdArray,

   288             TTransferOptions  aTransferOptions );

   289 

   290         /** @param[in] aLandmarkParser An object which can parse landmark content.

   291         *   @param aTransferOptions A bitmap representing the options for the

   292         *       import operation. The bitmap values are defined by

   293         *   @ref _TTransferOptions.

   294         *   @returns A handle to the operation. */

   295         CPosLmOperation* ImportLandmarksL(

   296             CPosLandmarkParser&  aLandmarkParser,

   297             TTransferOptions  aTransferOptions );

   298 

   299         /** @param[in] aLandmarkParser An object which can parse landmark content.

   300         *   @param[in] aLandmarkSelection An array defining which of the parsed

   301         *   landmarks to import. The array items refer to the order in which

   302         *   @ref CPosLandmarkParser accesses the landmarks. 0 means the first

   303         *   parsed landmark, 1 means the second, etc. If the parser supports

   304         *   indexing, these numbers correspond to the index values used to

   305         *   access the landmarks in @ref CPosLandmarkParser::LandmarkLC. The

   306         *   index values must be positive numbers and less than the number of

   307         *   landmarks accessed by the parser, otherwise this function will

   308         *   panic with code @p EPosInvalidIndex. @p Note: that the indexes

   309         *   can be used regardless of whether the parser supports indexing or

   310         *   not.

   311         * @param aTransferOptions A bitmap representing the options for the

   312         *   import operation. The bitmap values are defined by

   313         *   @ref _TTransferOptions.

   314         * @returns A handle to the operation. */

   315         CPosLmOperation* ImportLandmarksL(

   316             CPosLandmarkParser&  aLandmarkParser,

   317             const RArray<TUint>&  aLandmarkSelection,

   318             TTransferOptions  aTransferOptions );

   319 

   320         /** @param[in] aImportOperation This object is returned by

   321         *   @ref ImportLandmarksL methods.

   322         *   @returns An object for iterating the landmarks added in the latest

   323         *   import operation. */

   324         CPosLmItemIterator* ImportedLandmarksIteratorL(

   325             CPosLmOperation*  aImportOperation );

   326 

   327     protected: // from CPosLandmarkDatabaseExtended

   328 

   329         /** Returns reference to category manager instance for this database. */

   330         virtual CPosLmCategoryManager& CategoryManager();

   331         

   332         /** Returns pointer to extension interface. Type of the 

   333          *  requested extension interface is supplied by caller in aExtensionId.

   334          *

   335          *  Ownership of returned object is not transferred to caller, it is kept by

   336          *  implementation.

   337          *  

   338          *  @param[in] aExtensionUid Type of requested extension

   339          *  @return Pointer to extension implementation, or NULL if not supported.

   340          */

   341         virtual void* GetExtension( TUid aExtensionUid );

   342         

   343     private:

   344 

   345         /**

   346         * C++ default constructor.

   347         */

   348         CPosLmLocalDatabase();

   349 

   350         /**

   351         * @param aDatabaseUri Database URI.

   352         */

   353         void ConstructL( TAny* aDatabaseUri );

   354 

   355         /**

   356         * Reads a landmark with the specified id from the database.

   357         *

   358         * @param[in] aLandmarkId A landmark id.

   359         * @param[in] aIsPartial ETrue to read partial information. EFalse to read

   360         *   full information.

   361         * @return The landmark.

   362         */

   363         CPosLandmark* CPosLmLocalDatabase::ReadLmLC(

   364             TPosLmItemId aLandmarkId,

   365             TBool aIsPartial );

   366 

   367         /**

   368         * Creates an import proxy operation. Caller takes ownership of the

   369         * operation.

   370         *

   371         * @param[in] aImportOp Import operation. Ownership is transferred.

   372         * @return Import proxy operation.

   373         */

   374         CPosLmOperation* CreateImportProxyL( CPosLmLocalImportOp* aImportOp );

   375 

   376         /**

   377         * Opens a landmark database.

   378         *

   379         * @param[in] aIsDefaultDb ETrue if the database is the default database.

   380         *   EFalse otherwise.

   381         */

   382         void OpenDatabaseL( TBool aIsDefaultDb );

   383 

   384         // Prohibit copy constructor if not deriving from CBase.

   385         CPosLmLocalDatabase( const CPosLmLocalDatabase& );

   386         // Prohibit assigment operator if not deriving from CBase.

   387         CPosLmLocalDatabase& operator=( const CPosLmLocalDatabase& );

   388 

   389     private:    // Data

   390 

   391         // Database access

   392         CPosLmLocalDbAccess* iDbAccess;

   393 

   394         // Disk utilities

   395         CPosLmDiskUtilities* iDiskUtilities;

   396 

   397         // Database location

   398         HBufC* iDbUri;

   399 

   400         // Partial read settings

   401         CPosLmPartialReadParameters* iPartialSettings;

   402 

   403         // Database drive

   404         TChar  iDbDrive;

   405 

   406         // Session to Landmarks Server.

   407         RPosLandmarkServer* iServer;

   408         RPosLmLocalAccessSubsession* iSubSession;

   409         RPosLmLocalNameIndex* iNameIndex;

   410 

   411         // Instance of category manager, for client

   412         CPosLmLocalCategoryManager* iCategoryManager;

   413 

   414         // Fast counters extension

   415         CPosLmLocalDbFastCounters* iFastCounters;

   416     };

   417 

   418 #endif      // CPOSLMLOCALDATABASE_H