--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/landmarks/locationlandmarks/localaccess/inc/epos_cposlmlocaldatabase.h Tue Feb 02 01:06:48 2010 +0200
@@ -0,0 +1,418 @@
+/*
+* Copyright (c) 2002-2007 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: Handle to a local landmark database.
+*
+*
+*/
+
+
+#ifndef CPOSLMLOCALDATABASE_H
+#define CPOSLMLOCALDATABASE_H
+
+#include <e32base.h>
+#include <epos_cposlandmarkdatabaseextended.h>
+#include <EPos_CPosLandmarkEncoder.h>
+#include <EPos_CPosLandmarkParser.h>
+#include <epos_cposlmdiskutilities.h>
+#include <epos_mposlmdatabasefastcounters.h>
+
+class CPosLmLocalDbAccess;
+class CPosLandmark;
+class RPosLandmarkServer;
+class RPosLmLocalNameIndex;
+class RPosLmLocalAccessSubsession;
+class CPosLmDiskUtilities;
+class CPosLmLocalImportOp;
+class CPosLmLocalCategoryManager;
+class CPosLmLocalDbFastCounters;
+
+/**
+* Handle to a local landmark database.
+*
+* This class contains functions for creating, iterating, reading, modifying
+* and deleting landmarks.
+*
+* @lib eposlmlocalaccess.lib
+*/
+class CPosLmLocalDatabase : public CPosLandmarkDatabaseExtended
+ {
+
+ public: // Constructors and destructor
+
+ /**
+ * Two-phased constructor.
+ *
+ * Opens a local landmark database specified by the database URI.
+ *
+ * @param[in] aDatabaseURI Database URI here represented as a path in the
+ * filesystem. If the URI is NULL the default landmark database will
+ * be loaded. The TAny pointer must be a HBufC pointer (a cast will be
+ * made). This class is instantiated by the ECom framework.
+ * @return A new instance of this class.
+ */
+ IMPORT_C static CPosLmLocalDatabase* OpenL( TAny* aDatabaseUri );
+
+ /**
+ * Destructor.
+ */
+ IMPORT_C ~CPosLmLocalDatabase();
+
+ public: // Data types
+
+ /** Specifies the type of database lock. */
+ enum TLockType
+ {
+ EUnlocked = 0,
+ EReadLock,
+ EWriteLock
+ };
+
+ /** Specifies the transaction operation */
+ enum TTransactionOp
+ {
+ EStart,
+ ECommit,
+ ERollback
+ };
+
+ public: // New functions
+
+ /**
+ * Copies partial settings from aFromSetting to aToSetting.
+ *
+ * @param aFromSetting The source partial read parameter settings.
+ * @param aToSetting The destination partial read parameter settings.
+ */
+ void CopyPartialSettingsL(
+ const CPosLmPartialReadParameters& aFromSetting,
+ CPosLmPartialReadParameters& aToSetting );
+
+ /**
+ * Returns a handle to a database access object.
+ * @return A database access object.
+ */
+ IMPORT_C CPosLmLocalDbAccess* DatabaseAccess();
+
+ /**
+ * Leaves with KErrPosLmNotInitialized if initialization is needed.
+ */
+ IMPORT_C void LeaveIfInitializingIsNeededL();
+
+ /**
+ * Returns the drive unit for current database.
+ * @return A drive unit character.
+ */
+ TChar DatabaseDrive();
+
+ /**
+ * Returs a handle to the Landmarks Server.
+ * @return Handle to the server.
+ */
+ RPosLmLocalAccessSubsession& Session();
+
+ /**
+ * Registers an event in the Landmarks Server.
+ * @param aEventType Type of event.
+ * @param aId Optional landmarks id.
+ * @return KErrNone if successful. Otherwise any system-wide error code.
+ */
+ TInt RegisterEvent(
+ TPosLmEventType aEventType,
+ TPosLmItemId aId = KPosLmNullItemId );
+
+ /**
+ * Sets a lock on the database and puts a release lock function on the
+ * clean-up stack.
+ *
+ * Leaves with KErrLocked if the aquired lock is not compatible with
+ * previous locks on the database.
+ *
+ * @param aLockType The type of lock to set.
+ */
+ IMPORT_C void AquireLockLC( TLockType aLockType );
+
+ /**
+ * Sets a lock on the database. Does not put a release lock function on
+ * the clean-up stack. Useful for asynchronous operations.
+ *
+ * Leaves with KErrLocked if the aquired lock is not compatible with
+ * previous locks on the database.
+ *
+ * @param aLockType The type of lock to set.
+ */
+ IMPORT_C void AquireLockL( TLockType aLockType );
+
+ /**
+ * Releases a lock on the database. Useful for asynchronous operations
+ * that cannot put a release lock function on the clean-up stack.
+ *
+ * @param aLockType The type of lock to release.
+ */
+ IMPORT_C TInt ReleaseLock( TLockType aLockType );
+
+ /**
+ * Returs a handle to the Landmarks Server.
+ * @return Handle to the server.
+ */
+ IMPORT_C RPosLmLocalNameIndex& NameIndex();
+
+ /**
+ * Returs a handle to the Landmarks Server.
+ * @return Handle to the server.
+ */
+ IMPORT_C const RPosLmLocalNameIndex& NameIndex() const;
+
+ /** Starts new transaction for server data.
+ * Puts rollback action to cleanup stack.
+ * Used in landmark change transactions to ensure updating
+ * lm name index on server side */
+ IMPORT_C void BeginServerTransactionLC();
+
+ /** Starts new transaction for server data.
+ * Used in landmark change transactions to ensure updating
+ * lm name index on server side */
+ IMPORT_C void BeginServerTransactionL();
+
+ /** Commits current server data transaction and removes rollback from cleanup */
+ IMPORT_C void CommitServerTransactionLX();
+
+ /** Commits current server data transaction */
+ IMPORT_C void CommitServerTransactionL();
+
+ /** Cancels current transaction */
+ IMPORT_C void RollbackServerTransaction();
+
+ public: // From CPosLandmarkDatabase.
+
+ /** @returns @p ETrue if the database is in need of initialization,
+ * otherwise @p EFalse. */
+ TBool IsInitializingNeeded() const;
+
+ /** @returns A handle to the operation. */
+ CPosLmOperation* InitializeL();
+
+ /** @param aLandmarkId The ID of the landmark to read.
+ * @returns The requested landmark. The landmark object is put on the
+ * cleanup stack. */
+ CPosLandmark* ReadLandmarkLC( TPosLmItemId aLandmarkId );
+
+ /** @return The landmark iterator. */
+ CPosLmItemIterator* LandmarkIteratorL();
+
+ /** @param[in] aSortPref A sort preference object.
+ * @return The landmark iterator. */
+ CPosLmItemIterator* LandmarkIteratorL( const TPosLmSortPref& aSortPref );
+
+ /** @param[in,out] aLandmark The landmark to add.
+ * @return The ID of the new landmark. */
+ TPosLmItemId AddLandmarkL( CPosLandmark& aLandmark );
+
+ /** @param[in] aLandmark The new landmark data. */
+ void UpdateLandmarkL( const CPosLandmark& aLandmark );
+
+ /** @param aLandmarkId The ID of the landmark to remove.*/
+ void RemoveLandmarkL( TPosLmItemId aLandmarkId );
+
+ /** @param aLandmarkIdArray The IDs of the landmarks to remove.
+ * @returns A handle to the operation. */
+ CPosLmOperation* RemoveLandmarksL(
+ const RArray<TPosLmItemId>& aLandmarkIdArray );
+
+ /** @returns A handle to the operation. */
+ CPosLmOperation* RemoveAllLandmarksL();
+
+ /** @returns The current partial read parameters. */
+ CPosLmPartialReadParameters* PartialReadParametersLC();
+
+ /** @param aPartialSettings The new partial read parameters. */
+ void SetPartialReadParametersL(
+ const CPosLmPartialReadParameters& aPartialSettings );
+
+ /** @param The ID of the landmark to read.
+ * @returns The requested landmark. The landmark object will only
+ * contain the attributes defined in the partial read attributes. The
+ * landmark object is put on the cleanup stack. */
+ CPosLandmark* ReadPartialLandmarkLC( TPosLmItemId aLandmarkId );
+
+ /** @param aLandmarkIdArray An array with IDs of the landmarks to read.
+ * @returns A handle to the operation. */
+ CPosLmOperation* PreparePartialLandmarksL(
+ const RArray<TPosLmItemId>& aLandmarkIdArray );
+
+ /** @param aPreparePartialLandmarkOperation The operation object returned
+ * by the @ref PreparePartialLandmarksL function.
+ * @returns An array containing the prepared partial landmark objects. */
+ CArrayPtr<CPosLandmark>* TakePreparedPartialLandmarksL(
+ CPosLmOperation* aPreparePartialLandmarkOperation );
+
+ /** @returns The database URI. The URI is put on the cleanup stack. */
+ HBufC* DatabaseUriLC();
+
+ /** @returns Size information for the database. */
+ TSize SizeL();
+
+ /** @returns A handle to the operation. */
+ CPosLmOperation* CompactL();
+
+ /** @param[out] aEvent Will contain the event information when an event occurs.
+ * @param[out] aStatus Will be completed with @p KErrNone if an event
+ * occurs and an error code if some error was encountered. */
+ void NotifyDatabaseEvent(
+ TPosLmEvent& aEvent,
+ TRequestStatus& aStatus );
+
+ /** @return @p KErrNone if the request was successfully cancelled,
+ * otherwise a system wide error code. */
+ TInt CancelNotifyDatabaseEvent();
+
+ /** @param[in] aLandmarkEncoder A landmark encoder object.
+ * @param[in] aLandmarkIdArray The landmarks which should be exported.
+ * @param[in] aTransferOptions A bitmap representing the options for the
+ * export operation. The bitmap values are defined by
+ * @ref _TTransferOptions.
+ * @returns A handle to the operation. */
+ CPosLmOperation* ExportLandmarksL(
+ CPosLandmarkEncoder& aLandmarkEncoder,
+ const RArray<TPosLmItemId>& aLandmarkIdArray,
+ TTransferOptions aTransferOptions );
+
+ /** @param[in] aLandmarkParser An object which can parse landmark content.
+ * @param aTransferOptions A bitmap representing the options for the
+ * import operation. The bitmap values are defined by
+ * @ref _TTransferOptions.
+ * @returns A handle to the operation. */
+ CPosLmOperation* ImportLandmarksL(
+ CPosLandmarkParser& aLandmarkParser,
+ TTransferOptions aTransferOptions );
+
+ /** @param[in] aLandmarkParser An object which can parse landmark content.
+ * @param[in] aLandmarkSelection An array defining which of the parsed
+ * landmarks to import. The array items refer to the order in which
+ * @ref CPosLandmarkParser accesses the landmarks. 0 means the first
+ * parsed landmark, 1 means the second, etc. If the parser supports
+ * indexing, these numbers correspond to the index values used to
+ * access the landmarks in @ref CPosLandmarkParser::LandmarkLC. The
+ * index values must be positive numbers and less than the number of
+ * landmarks accessed by the parser, otherwise this function will
+ * panic with code @p EPosInvalidIndex. @p Note: that the indexes
+ * can be used regardless of whether the parser supports indexing or
+ * not.
+ * @param aTransferOptions A bitmap representing the options for the
+ * import operation. The bitmap values are defined by
+ * @ref _TTransferOptions.
+ * @returns A handle to the operation. */
+ CPosLmOperation* ImportLandmarksL(
+ CPosLandmarkParser& aLandmarkParser,
+ const RArray<TUint>& aLandmarkSelection,
+ TTransferOptions aTransferOptions );
+
+ /** @param[in] aImportOperation This object is returned by
+ * @ref ImportLandmarksL methods.
+ * @returns An object for iterating the landmarks added in the latest
+ * import operation. */
+ CPosLmItemIterator* ImportedLandmarksIteratorL(
+ CPosLmOperation* aImportOperation );
+
+ protected: // from CPosLandmarkDatabaseExtended
+
+ /** Returns reference to category manager instance for this database. */
+ virtual CPosLmCategoryManager& CategoryManager();
+
+ /** Returns pointer to extension interface. Type of the
+ * requested extension interface is supplied by caller in aExtensionId.
+ *
+ * Ownership of returned object is not transferred to caller, it is kept by
+ * implementation.
+ *
+ * @param[in] aExtensionUid Type of requested extension
+ * @return Pointer to extension implementation, or NULL if not supported.
+ */
+ virtual void* GetExtension( TUid aExtensionUid );
+
+ private:
+
+ /**
+ * C++ default constructor.
+ */
+ CPosLmLocalDatabase();
+
+ /**
+ * @param aDatabaseUri Database URI.
+ */
+ void ConstructL( TAny* aDatabaseUri );
+
+ /**
+ * Reads a landmark with the specified id from the database.
+ *
+ * @param[in] aLandmarkId A landmark id.
+ * @param[in] aIsPartial ETrue to read partial information. EFalse to read
+ * full information.
+ * @return The landmark.
+ */
+ CPosLandmark* CPosLmLocalDatabase::ReadLmLC(
+ TPosLmItemId aLandmarkId,
+ TBool aIsPartial );
+
+ /**
+ * Creates an import proxy operation. Caller takes ownership of the
+ * operation.
+ *
+ * @param[in] aImportOp Import operation. Ownership is transferred.
+ * @return Import proxy operation.
+ */
+ CPosLmOperation* CreateImportProxyL( CPosLmLocalImportOp* aImportOp );
+
+ /**
+ * Opens a landmark database.
+ *
+ * @param[in] aIsDefaultDb ETrue if the database is the default database.
+ * EFalse otherwise.
+ */
+ void OpenDatabaseL( TBool aIsDefaultDb );
+
+ // Prohibit copy constructor if not deriving from CBase.
+ CPosLmLocalDatabase( const CPosLmLocalDatabase& );
+ // Prohibit assigment operator if not deriving from CBase.
+ CPosLmLocalDatabase& operator=( const CPosLmLocalDatabase& );
+
+ private: // Data
+
+ // Database access
+ CPosLmLocalDbAccess* iDbAccess;
+
+ // Disk utilities
+ CPosLmDiskUtilities* iDiskUtilities;
+
+ // Database location
+ HBufC* iDbUri;
+
+ // Partial read settings
+ CPosLmPartialReadParameters* iPartialSettings;
+
+ // Database drive
+ TChar iDbDrive;
+
+ // Session to Landmarks Server.
+ RPosLandmarkServer* iServer;
+ RPosLmLocalAccessSubsession* iSubSession;
+ RPosLmLocalNameIndex* iNameIndex;
+
+ // Instance of category manager, for client
+ CPosLmLocalCategoryManager* iCategoryManager;
+
+ // Fast counters extension
+ CPosLmLocalDbFastCounters* iFastCounters;
+ };
+
+#endif // CPOSLMLOCALDATABASE_H