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

    15  *

    16 */

    17 

    18 

    19 #ifndef MLAPILANDMARK_H

    20 #define MLAPILANDMARK_H

    21 

    22 // INTERNAL INCLUDES

    23 #include    <e32std.h>

    24 

    25 // FORWARD DECLARATIONS

    26 class TLocality;

    27 class CLAPIAddressInfo;

    28 

    29 // Landmark item id definition

    30 typedef TUint32 TLAPIItemId;

    31 

    32 // Null landmark id definition

    33 const TLAPIItemId KLAPINullItemId = 0;

    34 

    35 // Landmark attributes. See CPosLandmark attributes for more detail

    36 // These attributes are used by Location API when reading landmark data

    37 enum TLAPILandmarkAttributesList

    38 {

    39     // No attributes

    40     ELAPILmNoAttributes = 0x0000,

    41     // The name of the landmark

    42     ELAPILmAttrName = 0x0001,

    43     // The position of the landmark

    44     ELAPILmAttrPosition = 0x0002,

    45     // The categories of the landmark

    46     ELAPILmAttrCategoryInfo = 0x0008,

    47     // The description of the landmark

    48     ELAPILmAttrDescription = 0x0020,

    49     // Additional attributes (not applicable to native API)

    50     ELAPILmAttrAddressInfo = 0x1000

    51 };

    52 

    53 // Address info fields which can be set to a landmark

    54 enum TLAPIAddressInfoFields

    55 {

    56     // Address field denoting address extension, e.g. flat number

    57     ELAPIAddressInfoExtension = 1,

    58     // Address field denoting street name and number

    59     ELAPIAddressInfoStreet,

    60     // Address field denoting zip or postal code

    61     ELAPIAddressInfoPostalCode,

    62     // Address field denoting town or city name

    63     ELAPIAddressInfoCity,

    64     // Address field denoting a county, which is between a state and a city

    65     ELAPIAddressInfoCounty,

    66     // Address field denoting state or province

    67     ELAPIAddressInfoState,

    68     // Address field denoting country

    69     ELAPIAddressInfoCountry,

    70     // Address field denoting country as a two-letter ISO 3166-1 code

    71     ELAPIAddressInfoCountryCode,

    72     // Address field denoting a municipal district

    73     ELAPIAddressInfoDistrict,

    74     // Address field denoting a building name

    75     ELAPIAddressInfoBuildingName,

    76     // Address field denoting a building floor

    77     ELAPIAddressInfoBuildingFloor,

    78     // Address field denoting a building room

    79     ELAPIAddressInfoBuildingRoom,

    80     // Address field denoting a building zone

    81     ELAPIAddressInfoBuildingZone,

    82     // Address field denoting a street in a crossing

    83     ELAPIAddressInfoCrossing1,

    84     // Address field denoting a street in a crossing (2nd)

    85     ELAPIAddressInfoCrossing2,

    86     // Address field denoting a URL for this place.

    87     ELAPIAddressInfoUrl,

    88     // Address field denoting a phone number for this place

    89     ELAPIAddressInfoPhoneNumber,

    90     // Number of addressInfo fields

    91     ELAPINumAddressInfos = ELAPIAddressInfoPhoneNumber

    92 };

    93 

    94 /**

    95  * Interface to a single Location API native landmark.

    96  *

    97  * @lib N/A

    98  * @since S60 3.2

    99  */

   100 NONSHARABLE_CLASS(MLAPILandmark)

   101 {

   102 

   103 public: // New functions

   104 

   105     /**

   106      * Returns the unique id of this landmark object.

   107      *

   108      * It this landmark does not belong to any landmark store,

   109      * KLAPINullItemId is returned.

   110      *

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

   112      * during the database operations

   113      *

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

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

   116      */

   117     virtual TLAPIItemId Id() const = 0;

   118 

   119     /**

   120      * Sets the name of this landmark.

   121      *

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

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

   124      * with KErrArgument

   125      *

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

   127      */

   128     virtual void SetNameL(const TDesC& aName) = 0;

   129 

   130     /**

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

   132      * if there is no description in this landmark yet

   133      *

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

   135      * is read from the native landmark store.

   136      *

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

   138      *         landmark does not have a name yet

   139      */

   140     virtual const TDesC& NameL() = 0;

   141 

   142     /**

   143      * Sets the description of this landmark.

   144      *

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

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

   147      * ignored

   148      *

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

   150      *        NULL argument will remove the existing value when the

   151      *        landmark is stored again

   152      */

   153     virtual void SetDescriptionL(const TDesC* aDescription) = 0;

   154 

   155     /**

   156      * Returns the description of this landmark

   157      *

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

   159      * landmark is read from the native landmark store.

   160      *

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

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

   163      *         to the caller

   164      */

   165     virtual const TDesC* DescriptionL() = 0;

   166 

   167     /**

   168      * Sets coordinates for this landmark

   169      *

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

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

   172      * of the landmark

   173      *

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

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

   176      * when the item is committed to the native database

   177      *

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

   179      *        argument will remove the existing value when then landmark

   180      *        is stored again

   181      */

   182     virtual void SetCoordinatesL(const TLocality* aCoordinates) = 0;

   183 

   184     /**

   185      * Returns the coordinates of this landmark

   186      *

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

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

   189      *

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

   191      * landmark are read from the native landmark store.

   192      *

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

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

   195      *         to the caller.

   196      */

   197     virtual const TLocality* CoordinatesL() = 0;

   198 

   199     /**

   200      * Sets the address information in this landmark.

   201      *

   202      * NULL argument indicates that the address information should

   203      * be removed from the landmark

   204      *

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

   206      *        The ownership is transferred to this class

   207      */

   208     virtual void SetAddressInfoL(CLAPIAddressInfo* aAddressInfo) = 0;

   209 

   210     /**

   211      * Returns the address information for this landmark.

   212      *

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

   214      * yet loaded.

   215      *

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

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

   218      * subsequently.

   219      *

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

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

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

   223      */

   224     virtual const CLAPIAddressInfo* AddressInfoL() = 0;

   225 

   226 protected: // Constructor

   227 

   228     /**

   229      * Destructor. Does not allow to delete objects via this interface

   230      */

   231     virtual ~MLAPILandmark()

   232     {}

   233 

   234 }

   235 ;

   236 

   237 #endif // MLAPILANDMARK_H

   238 // End of file