--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/javaextensions/location/landmarks/inc/clapilandmarkstore.h Tue Apr 27 16:30:29 2010 +0300
@@ -0,0 +1,301 @@
+/*
+* Copyright (c) 2008 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: Implements the native part of the Location API landmark store
+ *
+*/
+
+
+#ifndef CLAPILANDMARKSTORE_H
+#define CLAPILANDMARKSTORE_H
+
+// INTERNAL INCLUDES
+#include "mlapilandmarkstore.h"
+#include "mlapilmdatabaseobserver.h"
+#include "mlapilandmark.h"
+
+// EXTERNAL INCLUDES
+#include <e32def.h>
+#include <e32base.h>
+#include <EPos_Landmarks.h>
+
+// FORWARD DECLARATIONS
+class CLAPILandmarkSearchFactory;
+class TLAPISearchCriteria;
+class CPosLandmarkDatabase;
+class CPosLandmark;
+class MLAPICategoryManager;
+class MLAPILmDatabaseEventNotifier;
+
+/**
+ * Implements the native part of Location API landmark store.
+ *
+ * This class provides the basic functionalities for handling
+ * individual landmarks such as adding, deleting and updating landmarks
+ *
+ * The stores are available always when it once has been opened. This
+ * is because some items may still exists in the java side after the
+ * store has been closed. Function calls to a closed store leaves with
+ * KErrSessionClosed. The stores cannot be closed explicitly from the Java
+ * but only when a store is deleted from the device
+ *
+ * Ensuring that stores are not always open prevents the API to reserve
+ * huge amount of memory if many stores are used concurrently
+ *
+ * @lib N/A
+ * @since S60 3.2
+ */
+NONSHARABLE_CLASS(CLAPILandmarkStore) : public CBase,
+ public MLAPILandmarkStore
+{
+public: // Type definitions
+
+ // Construction parameters of this class
+ class TCtorParams
+ {
+ public:
+ // The ownership of these are transferred in the construction
+ CPosLandmarkDatabase* iLandmarkDatabase;
+ MLAPICategoryManager* iCategoryManager;
+ MLAPILmDatabaseEventNotifier* iEventNotifier;
+ };
+
+public: // Constructors and destructor
+
+ /**
+ * Two-phased constructor. Creates an instance from this class
+ * The caller takes the ownership of the returned instance
+ *
+ * @param aParams Construction parameters of this class
+ * @return New instance from this class
+ */
+ static CLAPILandmarkStore* NewL(const TCtorParams& aParams);
+
+ /**
+ * Two-phased constructor. Creates an instance from this class
+ * The caller takes the ownership of the returned instance which
+ * is left to the cleanup stack
+ *
+ * @param aParams Construction parameters of this class
+ * @return New instance from this class
+ */
+ static CLAPILandmarkStore* NewLC(const TCtorParams& aParams);
+
+ /**
+ * Destructor.
+ */
+ virtual ~CLAPILandmarkStore();
+
+public: // From MLAPILandmarkStore
+
+ /**
+ * Reads the full landmark data from the database. The data
+ * is added to the item which is passed as a parameter. Note
+ * that this function may be time consuming if it is called
+ * for huge amount of landmarks subsequently.
+ *
+ * The function should only be used when the item is needed
+ * to be fully writen into the native database. The operation
+ *
+ * @param aLandmark The landmark which will be read from the database
+ */
+ void ReadFullLandmarkL(CLAPILandmark& aLandmark);
+
+ /**
+ * Reads the requested attributes to a landmark from the native database.
+ * It also possible to read certain position fields from the native
+ * database.
+ *
+ * @param aLandmark The landmark which is to be read
+ * @param aAttributes The attributes which are read
+ * @param aAddressInfos The requested address info fields which
+ * are read from the native database. If this parameter is
+ * NULL, then no position fields are read. Note that the
+ * ownership of the array does NOT transfer to this class
+ */
+ void ReadLandmarkAttributesL(
+ CLAPILandmark& aLandmark,
+ const TUint aAttributes,
+ const RArray< TUint>* aAddressInfos);
+
+ /**
+ * Returns the category manager for this database. If NULL is returned
+ * this database does not support categories at all.
+ *
+ * @return Category manager for this landmark store. The ownership is
+ * NOT transferred to the caller. NULL indicates that the store
+ * does not support category management
+ */
+ MLAPICategoryManager* CategoryManagerL() const;
+
+ /**
+ * Indicates that a landmark is going to be disposed. This removes
+ * any possible references to the landmark from this store if the
+ * landmark belongs to the store
+ *
+ * @param aLandmark A references to the disposed landmark object
+ */
+ void LandmarkDisposed(CLAPILandmark& aLandmark);
+
+public: // New functions
+
+ /**
+ * Returns the URI of this landmark store
+ * @return The URI of the landmark store
+ */
+ const TDesC& StoreUri() const;
+
+ /**
+ * Returns an array of landmarks based on the search attributes and
+ * initialization parameters. The caller takes the ownership of the
+ * returned array.
+ *
+ * Currently it is possible to search using three different parameters
+ * and additionally a different mixture of these parameters. If no
+ * criteria is specified, all landmarks in the store will be returned
+ *
+ * - A text with attributes can be specified to perform a search
+ * from every string field in a landmark
+ * - A category name can be specified to perform a search from
+ * the specified category
+ * - An area can be specified to perform an area specific search
+ *
+ * @param aAttributes The attributes which will be pre-initialized
+ * to the matched landmarks. Note that initializing time depends
+ * on the number of initialized attributes
+ * @param aSearchCriteria The search criteria which is used to search
+ * the landmarks. NULL matches all landmarks
+ * @return An array of landmark. The caller takes the ownership of the
+ * array and the landmarks in it
+ */
+ CArrayPtr< CLAPILandmark>* LandmarksL(
+ const TUint aAttributes,
+ const TLAPISearchCriteria* aSearchCriteria);
+
+ /**
+ * Adds a new landmark to this landmark store. If the landmark already
+ * belongs to this store nothing happens
+ *
+ * @param aLandmark The landmark which will be added
+ */
+ void AddLandmarkL(CLAPILandmark& aLandmark);
+
+ /**
+ * Updates an existing landmark in the database. The data is copied
+ * from aLandmark object and added to the existing landmark in the
+ * database.
+ *
+ * This operation leaves with KErrNotFound if there is no such landmark
+ * in the database
+ *
+ * @param aLandmark The landmark which will be updated
+ */
+ void UpdateLandmarkL(CLAPILandmark& aLandmark);
+
+ /**
+ * Removes an existing landmark from this landmark store
+ *
+ * The call is silently ignored if the landmark does not belong to this
+ * store or if it has already been removed.
+ *
+ * @param aLandmark The landmark which is to be removed
+ */
+ void RemoveLandmarkL(CLAPILandmark& aLandmark);
+
+ /**
+ * Compacts the native database if it is necessary.
+ *
+ * The compacting is done synchronously so it may take some time to complete
+ * depending on the number of the landmarks and categories which
+ * are stored to this landmark store
+ */
+ void CompactIfNeededL();
+
+ /**
+ * Closes this landmark store. Note that this does not delete
+ * this object but only closes the access to the native database
+ * The object is still usable, but invocations will leave with
+ * KErrSessionClosed.
+ *
+ * Stores can be closed internally when the object needs to be
+ * deleted or externally when the store is needed to be closed
+ * due to, for example, database deletion.
+ */
+ void Close();
+
+private: // New functions
+
+ /**
+ * Converts prepared landmarks to Location API landmarks
+ * Note that this is only needed because of the cleanup problems
+ * related to ownership transferring of CArrayPtr which comes
+ * from Landmarks API
+ *
+ * @param aSrcArray The array from which the objects are created
+ * on return, the array is empty
+ * @param aDestArray The array to which the new landmarks are added
+ */
+ void HandlePreparedLandmarksL(
+ CArrayPtr< CPosLandmark>& aSrcArray,
+ CArrayPtr< CLAPILandmark>& aDestArray);
+
+ /**
+ * Refreshes all landmarks which match for the given identifier.
+ * Note that this operation may be a very huge operation if one
+ * landmark has many references from the Java side
+ *
+ * @param aLandmarkId The identifier of updated landmarks
+ * @param aRemoveFromStore Indicates that the refreshed landmarks
+ * should be removed from this landmark store. By default,
+ * the landmarks are not removed
+ */
+ void RefreshLandmarksL(
+ TLAPIItemId aLandmarkId,
+ TBool aRemoveFromStore = EFalse);
+
+private: // Construtors
+
+ /**
+ * C++ constructor.
+ * @param aParams Construction parameters
+ */
+ CLAPILandmarkStore(const TCtorParams& aParams);
+
+ /**
+ * Second phase constructor
+ */
+ void ConstructL();
+
+private: // Data
+
+ // All landmark objects. Used
+ RPointerArray< CLAPILandmark> iLandmarks;
+
+ // Landmark database. Owned
+ CPosLandmarkDatabase* iLandmarkDatabase;
+
+ // Category manager. Owned
+ MLAPICategoryManager* iCategoryManager;
+
+ // Database event notifier. Owned
+ MLAPILmDatabaseEventNotifier* iEventNotifier;
+
+ // Landmark search factory. Owned
+ CLAPILandmarkSearchFactory* iSearchFactory;
+
+ // The URI of this store. Owned
+ HBufC* iStoreUri;
+};
+
+#endif // CLAPILANDMARKSTORE_H
+// End of file