1 /*

     2 * Copyright (c) 2008 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:  Implements the native part of the Location API landmark store

    15  *

    16 */

    17 

    18 

    19 #ifndef CLAPILANDMARKSTORE_H

    20 #define CLAPILANDMARKSTORE_H

    21 

    22 // INTERNAL INCLUDES

    23 #include    "mlapilandmarkstore.h"

    24 #include    "mlapilmdatabaseobserver.h"

    25 #include    "mlapilandmark.h"

    26 

    27 // EXTERNAL INCLUDES

    28 #include    <e32def.h>

    29 #include    <e32base.h>

    30 #include    <EPos_Landmarks.h>

    31 

    32 // FORWARD DECLARATIONS

    33 class CLAPILandmarkSearchFactory;

    34 class TLAPISearchCriteria;

    35 class CPosLandmarkDatabase;

    36 class CPosLandmark;

    37 class MLAPICategoryManager;

    38 class MLAPILmDatabaseEventNotifier;

    39 

    40 /**

    41  * Implements the native part of Location API landmark store.

    42  *

    43  * This class provides the basic functionalities for handling

    44  * individual landmarks such as adding, deleting and updating landmarks

    45  *

    46  * The stores are available always when it once has been opened. This

    47  * is because some items may still exists in the java side after the

    48  * store has been closed. Function calls to a closed store leaves with

    49  * KErrSessionClosed. The stores cannot be closed explicitly from the Java

    50  * but only when a store is deleted from the device

    51  *

    52  * Ensuring that stores are not always open prevents the API to reserve

    53  * huge amount of memory if many stores are used concurrently

    54  *

    55  * @lib N/A

    56  * @since S60 3.2

    57  */

    58 NONSHARABLE_CLASS(CLAPILandmarkStore) : public CBase,

    59         public MLAPILandmarkStore

    60 {

    61 public: // Type definitions

    62 

    63     // Construction parameters of this class

    64     class TCtorParams

    65     {

    66     public:

    67         // The ownership of these are transferred in the construction

    68         CPosLandmarkDatabase* iLandmarkDatabase;

    69         MLAPICategoryManager* iCategoryManager;

    70         MLAPILmDatabaseEventNotifier* iEventNotifier;

    71     };

    72 

    73 public: // Constructors and destructor

    74 

    75     /**

    76      * Two-phased constructor. Creates an instance from this class

    77      * The caller takes the ownership of the returned instance

    78      *

    79      * @param aParams Construction parameters of this class

    80      * @return New instance from this class

    81      */

    82     static CLAPILandmarkStore* NewL(const TCtorParams& aParams);

    83 

    84     /**

    85      * Two-phased constructor. Creates an instance from this class

    86      * The caller takes the ownership of the returned instance which

    87      * is left to the cleanup stack

    88      *

    89      * @param aParams Construction parameters of this class

    90      * @return New instance from this class

    91      */

    92     static CLAPILandmarkStore* NewLC(const TCtorParams& aParams);

    93 

    94     /**

    95      * Destructor.

    96      */

    97     virtual ~CLAPILandmarkStore();

    98 

    99 public: // From MLAPILandmarkStore

   100 

   101     /**

   102      * Reads the full landmark data from the database. The data

   103      * is added to the item which is passed as a parameter. Note

   104      * that this function may be time consuming if it is called

   105      * for huge amount of landmarks subsequently.

   106      *

   107      * The function should only be used when the item is needed

   108      * to be fully writen into the native database. The operation

   109      *

   110      * @param aLandmark The landmark which will be read from the database

   111      */

   112     void ReadFullLandmarkL(CLAPILandmark& aLandmark);

   113 

   114     /**

   115      * Reads the requested attributes to a landmark from the native database.

   116      * It also possible to read certain position fields from the native

   117      * database.

   118      *

   119      * @param aLandmark The landmark which is to be read

   120      * @param aAttributes The attributes which are read

   121      * @param aAddressInfos The requested address info fields which

   122      *        are read from the native database. If this parameter is

   123      *        NULL, then no position fields are read. Note that the

   124      *        ownership of the array does NOT transfer to this class

   125      */

   126     void ReadLandmarkAttributesL(

   127         CLAPILandmark& aLandmark,

   128         const TUint aAttributes,

   129         const RArray< TUint>* aAddressInfos);

   130 

   131     /**

   132      * Returns the category manager for this database. If NULL is returned

   133      * this database does not support categories at all.

   134      *

   135      * @return Category manager for this landmark store. The ownership is

   136      *         NOT transferred to the caller. NULL indicates that the store

   137      *         does not support category management

   138      */

   139     MLAPICategoryManager* CategoryManagerL() const;

   140 

   141     /**

   142      * Indicates that a landmark is going to be disposed. This removes

   143      * any possible references to the landmark from this store if the

   144      * landmark belongs to the store

   145      *

   146      * @param aLandmark A references to the disposed landmark object

   147      */

   148     void LandmarkDisposed(CLAPILandmark& aLandmark);

   149 

   150 public: // New functions

   151 

   152     /**

   153      * Returns the URI of this landmark store

   154      * @return The URI of the landmark store

   155      */

   156     const TDesC& StoreUri() const;

   157 

   158     /**

   159      * Returns an array of landmarks based on the search attributes and

   160      * initialization parameters. The caller takes the ownership of the

   161      * returned array.

   162      *

   163      * Currently it is possible to search using three different parameters

   164      * and additionally a different mixture of these parameters. If no

   165      * criteria is specified, all landmarks in the store will be returned

   166      *

   167      *      - A text with attributes can be specified to perform a search

   168      *        from every string field in a landmark

   169      *      - A category name can be specified to perform a search from

   170      *        the specified category

   171      *      - An area can be specified to perform an area specific search

   172      *

   173      * @param aAttributes The attributes which will be pre-initialized

   174      *        to the matched landmarks. Note that initializing time depends

   175      *        on the number of initialized attributes

   176      * @param aSearchCriteria The search criteria which is used to search

   177      *        the landmarks. NULL matches all landmarks

   178      * @return An array of landmark. The caller takes the ownership of the

   179      *         array and the landmarks in it

   180      */

   181     CArrayPtr< CLAPILandmark>* LandmarksL(

   182         const TUint aAttributes,

   183         const TLAPISearchCriteria* aSearchCriteria);

   184 

   185     /**

   186      * Adds a new landmark to this landmark store. If the landmark already

   187      * belongs to this store nothing happens

   188      *

   189      * @param aLandmark The landmark which will be added

   190      */

   191     void AddLandmarkL(CLAPILandmark& aLandmark);

   192 

   193     /**

   194      * Updates an existing landmark in the database. The data is copied

   195      * from aLandmark object and added to the existing landmark in the

   196      * database.

   197      *

   198      * This operation leaves with KErrNotFound if there is no such landmark

   199      * in the database

   200      *

   201      * @param aLandmark The landmark which will be updated

   202      */

   203     void UpdateLandmarkL(CLAPILandmark& aLandmark);

   204 

   205     /**

   206      * Removes an existing landmark from this landmark store

   207      *

   208      * The call is silently ignored if the landmark does not belong to this

   209      * store or if it has already been removed.

   210      *

   211      * @param aLandmark The landmark which is to be removed

   212      */

   213     void RemoveLandmarkL(CLAPILandmark& aLandmark);

   214 

   215     /**

   216      * Compacts the native database if it is necessary.

   217      *

   218      * The compacting is done synchronously so it may take some time to complete

   219      * depending on the number of the landmarks and categories which

   220      * are stored to this landmark store

   221      */

   222     void CompactIfNeededL();

   223 

   224     /**

   225      * Closes this landmark store. Note that this does not delete

   226      * this object but only closes the access to the native database

   227      * The object is still usable, but invocations will leave with

   228      * KErrSessionClosed.

   229      *

   230      * Stores can be closed internally when the object needs to be

   231      * deleted or externally when the store is needed to be closed

   232      * due to, for example, database deletion.

   233      */

   234     void Close();

   235 

   236 private: // New functions

   237 

   238     /**

   239      * Converts prepared landmarks to Location API landmarks

   240      * Note that this is only needed because of the cleanup problems

   241      * related to ownership transferring of CArrayPtr which comes

   242      * from Landmarks API

   243      *

   244      * @param aSrcArray The array from which the objects are created

   245      *        on return, the array is empty

   246      * @param aDestArray The array to which the new landmarks are added

   247      */

   248     void HandlePreparedLandmarksL(

   249         CArrayPtr< CPosLandmark>& aSrcArray,

   250         CArrayPtr< CLAPILandmark>& aDestArray);

   251 

   252     /**

   253      * Refreshes all landmarks which match for the given identifier.

   254      * Note that this operation may be a very huge operation if one

   255      * landmark has many references from the Java side

   256      *

   257      * @param aLandmarkId The identifier of updated landmarks

   258      * @param aRemoveFromStore Indicates that the refreshed landmarks

   259      *        should be removed from this landmark store. By default,

   260      *        the landmarks are not removed

   261      */

   262     void RefreshLandmarksL(

   263         TLAPIItemId aLandmarkId,

   264         TBool aRemoveFromStore = EFalse);

   265 

   266 private: // Construtors

   267 

   268     /**

   269      * C++ constructor.

   270      * @param aParams Construction parameters

   271      */

   272     CLAPILandmarkStore(const TCtorParams& aParams);

   273 

   274     /**

   275      * Second phase constructor

   276      */

   277     void ConstructL();

   278 

   279 private: // Data

   280 

   281     // All landmark objects. Used

   282     RPointerArray< CLAPILandmark> iLandmarks;

   283 

   284     // Landmark database. Owned

   285     CPosLandmarkDatabase* iLandmarkDatabase;

   286 

   287     // Category manager. Owned

   288     MLAPICategoryManager* iCategoryManager;

   289 

   290     // Database event notifier. Owned

   291     MLAPILmDatabaseEventNotifier* iEventNotifier;

   292 

   293     // Landmark search factory. Owned

   294     CLAPILandmarkSearchFactory* iSearchFactory;

   295 

   296     // The URI of this store. Owned

   297     HBufC* iStoreUri;

   298 };

   299 

   300 #endif // CLAPILANDMARKSTORE_H

   301 // End of file