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 a single Location API native landmark

    15  *

    16 */

    17 

    18 

    19 #ifndef CLAPILANDMARK_H

    20 #define CLAPILANDMARK_H

    21 

    22 // INTERNAL INCLUDES

    23 #include    "mlapilandmark.h"

    24 

    25 // EXTERNAL INCLUDES

    26 #include    <e32base.h>

    27 #include    <lbsposition.h>

    28 

    29 // FORWARD DECLARATIONS

    30 class MLAPILandmarkStore;

    31 class CPosLandmark;

    32 

    33 /**

    34  * Implements a single Location API native landmark

    35  *

    36  * The landmark can have different attributes and address information

    37  * such as name, description, position or country and city information.

    38  *

    39  * A single landmark can be associated to many different categories but

    40  * the categories must defined in the store in which the landmark belongs

    41  * to. The landmark can implicitly belong to many different stores but

    42  * explicitly it can belong to one landmark store at a time.

    43  *

    44  * If the landmark is associated to a store it tries to read its data

    45  * when the data is requested from the object. This optimizes the

    46  * performance of the API in cases where the client does not need to

    47  * display the whole item at once.

    48  *

    49  * @lib N/A

    50  * @since S60 3.2

    51  */

    52 NONSHARABLE_CLASS(CLAPILandmark) : public CBase,

    53         public MLAPILandmark

    54 {

    55 public: // Constructors and destructor

    56 

    57     // Construction parameters of this class

    58     class TCtorParams

    59     {

    60     public:

    61         // The native landmark. NULL indicates that this landmark

    62         // is a new one and not from a landmark store

    63         CPosLandmark* iLandmark;

    64         // The database to which this landmark belongs to. NULL

    65         // indicates that this landmark is a new landmark

    66         MLAPILandmarkStore* iLandmarkStore;

    67     };

    68 

    69     /**

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

    71      * The caller takes the ownership of the returned instance

    72      *

    73      * @param aParams The construction parameters of this class

    74      * @return New instance from this class

    75      */

    76     static CLAPILandmark* NewL(const TCtorParams& aParams);

    77 

    78     /**

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

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

    81      * is left to the cleanup stack

    82      *

    83      * @param aParams The construction parameters of this class

    84      * @return New instance from this class

    85      */

    86     static CLAPILandmark* NewLC(const TCtorParams& aParams);

    87 

    88     /**

    89      * Destructor.

    90      */

    91     virtual ~CLAPILandmark();

    92 

    93 public: // From MLAPILandmark

    94 

    95     /**

    96      * Returns the unique id of this landmark object.

    97      *

    98      * If this landmark does not belong to any landmark store,

    99      * KLAPINullItemId is returned.

   100      *

   101      * The identifier cannot be externally changed. It is modified

   102      * during the database operations

   103      *

   104      * @return The item identifier of this landmark. KLAPINullItemId

   105      *         is returned if this landmark does not belong to a store

   106      */

   107     TLAPIItemId Id() const;

   108 

   109     /**

   110      * Sets the name of this landmark.

   111      *

   112      * The name must not be longer than the maximum specified length in

   113      * Landmarks API. Otherwise the saving of the landmark will fail

   114      * with KErrArgument

   115      *

   116      * @param aName The new name of the landmark.

   117      */

   118     void SetNameL(const TDesC& aName);

   119 

   120     /**

   121      * Returns the name of this landmark. KNullDesC will be returned

   122      * if there is no description in this landmark yet

   123      *

   124      * If the item belongs to a Landmark Store, the name of the item

   125      * is read from the native landmark store.

   126      *

   127      * @return The name of the landmark. KNullDesC is returned if the

   128      *         landmark does not have a name yet

   129      */

   130     const TDesC& NameL();

   131 

   132     /**

   133      * Sets the description of this landmark.

   134      *

   135      * The description must not be longer than the maximum specified length

   136      * in the Landmarks API Otherwise the rest of the description will be

   137      * ignored

   138      *

   139      * @param aDescription The new description of the landmark. Note that

   140      *        NULL argument will remove the existing value when the

   141      *        landmark is stored again

   142      */

   143     void SetDescriptionL(const TDesC* aDescription);

   144 

   145     /**

   146      * Returns the description of this landmark

   147      *

   148      * If the item belongs to a Landmark Store, the description of the

   149      * landmark is read from the native landmark store.

   150      *

   151      * @return The description of the landmark. NULL is returned if the landmark

   152      *         does not have a description. The ownership is NOT transferred

   153      *         to the caller

   154      */

   155     const TDesC* DescriptionL();

   156 

   157     /**

   158      * Sets coordinates for this landmark

   159      *

   160      * By default, the landmark does not have coordinates meaning that

   161      * an empty TLocality object is used when requesting the position

   162      * of the landmark

   163      *

   164      * Note that after setting the coordinates for a database item, the

   165      * database values will not be fetched anymore and are overwritten

   166      * when the item is committed to the native database

   167      *

   168      * @param aCoordinates Coordinates of this landmark. Note that NULL

   169      *        argument will remove the existing value when then landmark

   170      *        is stored again

   171      */

   172     void SetCoordinatesL(const TLocality* aCoordinates);

   173 

   174     /**

   175      * Returns the coordinates of this landmark

   176      *

   177      * By default, the landmark does not have coordinates meaning that

   178      * an empty TLocality object is used when requesting the position

   179      *

   180      * If the item belongs to a Landmark Store, the coordinates of the

   181      * landmark are read from the native landmark store.

   182      *

   183      * @return Coordinates of this landmark. NULL is returned if the landmark

   184      *         does not have coordinates. The ownership is NOT transferred

   185      *         to the caller.

   186      */

   187     const TLocality* CoordinatesL();

   188 

   189     /**

   190      * Sets the address information in this landmark.

   191      *

   192      * NULL argument indicates that the address information should

   193      * be removed from the landmark

   194      *

   195      * @param aAddressInfo The new address information for this landmark.

   196      *        The ownership is transferred to this class

   197      */

   198     void SetAddressInfoL(CLAPIAddressInfo* aAddressInfo);

   199 

   200     /**

   201      * Returns the address information for this landmark.

   202      *

   203      * The fields are loaded from the native database if those are not

   204      * yet loaded.

   205      *

   206      * Note that depending from the amount of supported address information,

   207      * this operation may be performance critical if done for many items

   208      * subsequently.

   209      *

   210      * @return The address information of this landmark. NULL or empty object

   211      *         is returned if the landmark does not have address information.

   212      *         The caller does NOT take the ownership of the object

   213      */

   214     const CLAPIAddressInfo* AddressInfoL();

   215 

   216 public: // New functions

   217 

   218     /**

   219      * Prepares the item for saving. This operation must be called

   220      * always when the item is to be persisted to some existing database

   221      * It guarantees that the data which has been modified is correctly

   222      * written and stored to the native database so, in practice, this

   223      * operation commits the changes made to the item after previous

   224      * call of PrepareForSaveL

   225      *

   226      * Note that at this point, any existing data will be overwritten

   227      * and the full item is loaded from the landmark store so this

   228      * should be used with caution and only when the item is to be

   229      * fully saved to a database or exported to some external module

   230      */

   231     void PrepareForSaveL();

   232 

   233     /**

   234      * Returns the native counterpart of this class. Note that

   235      * the object may not be up to date if PrepareForSaveL() has

   236      * not been called

   237      * @return Landmarks API landmark implementation

   238      */

   239     CPosLandmark& PosLandmark() const;

   240 

   241     /**

   242      * Sets new CPosLandmark object to this landmark. The existing

   243      * object will be replaced. The ownership is transferred to

   244      * this class.

   245      *

   246      * @param aLandmark New CPosLandmark object

   247      */

   248     void SetPosLandmark(CPosLandmark* aLandmark);

   249 

   250     /**

   251      * Associates this landmark to a landmark store.. The landmark can

   252      * belong to one landmark store at a time. If the landmark is transferred

   253      * to a different store, the old store will be notified

   254      *

   255      * @param aStore The store where this landmark has been added

   256      */

   257     void AssociateToStore(MLAPILandmarkStore* aStore);

   258 

   259     /**

   260      * Indicates that the store in which this landmark belongs to

   261      * has been closed

   262      */

   263     void StoreClosed();

   264 

   265 private: // New functions

   266 

   267     /**

   268      * Read address information values from the native CPosLandmark

   269      * object owned by this class.

   270      *

   271      * The values are read to iAddressInfo which must not be null.

   272      * Otherwise this function will panic

   273      *

   274      * @param aPositionFields The position fields which should be read

   275      *        from the native CPosLandmark object

   276      * @return The number of available position fields in the native

   277      *         landmark

   278      */

   279     TInt DoGetAddressInfoFieldValuesL(const RArray< TUint>& aPositionFields);

   280 

   281 private: // Constructors

   282 

   283     /**

   284      * Constructor

   285      * @param aParams The constructions parameters of this class

   286      */

   287     CLAPILandmark(const TCtorParams& aParams);

   288 

   289     /**

   290      * Second phase constructor

   291      */

   292     void ConstructL();

   293 

   294 private: // Data

   295 

   296     // The landmark store to which this landmark belongs. Used. Can be NULL

   297     MLAPILandmarkStore* iLandmarkStore;

   298     // Associated native landmark object. Owned

   299     CPosLandmark* iLandmark;

   300 

   301     // The name of the landmark. Owned

   302     HBufC* iLandmarkName;

   303     // The description of the landmark. Owned

   304     HBufC* iDescription;

   305     // Coordinates fo the landmark. Owned

   306     TLocality* iCoordinates;

   307     // Address information. Owned

   308     CLAPIAddressInfo* iAddressInfo;

   309 

   310     // Attributes of this landmark. This marks the landmark attributes

   311     // which are changed during the lifetime of the landmark.

   312     TUint iChangedAttributes;

   313 

   314 };

   315 

   316 #endif // CLAPILANDMARK_H

   317 // End of file