/*

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

 *

*/

#ifndef MLAPILANDMARK_H

#define MLAPILANDMARK_H

// INTERNAL INCLUDES

#include    <e32std.h>

// FORWARD DECLARATIONS

class TLocality;

class CLAPIAddressInfo;

// Landmark item id definition

typedef TUint32 TLAPIItemId;

// Null landmark id definition

const TLAPIItemId KLAPINullItemId = 0;

// Landmark attributes. See CPosLandmark attributes for more detail

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

enum TLAPILandmarkAttributesList

{

    // No attributes

    ELAPILmNoAttributes = 0x0000,

    // The name of the landmark

    ELAPILmAttrName = 0x0001,

    // The position of the landmark

    ELAPILmAttrPosition = 0x0002,

    // The categories of the landmark

    ELAPILmAttrCategoryInfo = 0x0008,

    // The description of the landmark

    ELAPILmAttrDescription = 0x0020,

    // Additional attributes (not applicable to native API)

    ELAPILmAttrAddressInfo = 0x1000

};

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

enum TLAPIAddressInfoFields

{

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

    ELAPIAddressInfoExtension = 1,

    // Address field denoting street name and number

    ELAPIAddressInfoStreet,

    // Address field denoting zip or postal code

    ELAPIAddressInfoPostalCode,

    // Address field denoting town or city name

    ELAPIAddressInfoCity,

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

    ELAPIAddressInfoCounty,

    // Address field denoting state or province

    ELAPIAddressInfoState,

    // Address field denoting country

    ELAPIAddressInfoCountry,

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

    ELAPIAddressInfoCountryCode,

    // Address field denoting a municipal district

    ELAPIAddressInfoDistrict,

    // Address field denoting a building name

    ELAPIAddressInfoBuildingName,

    // Address field denoting a building floor

    ELAPIAddressInfoBuildingFloor,

    // Address field denoting a building room

    ELAPIAddressInfoBuildingRoom,

    // Address field denoting a building zone

    ELAPIAddressInfoBuildingZone,

    // Address field denoting a street in a crossing

    ELAPIAddressInfoCrossing1,

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

    ELAPIAddressInfoCrossing2,

    // Address field denoting a URL for this place.

    ELAPIAddressInfoUrl,

    // Address field denoting a phone number for this place

    ELAPIAddressInfoPhoneNumber,

    // Number of addressInfo fields

    ELAPINumAddressInfos = ELAPIAddressInfoPhoneNumber

};

/**

 * Interface to a single Location API native landmark.

 *

 * @lib N/A

 * @since S60 3.2

 */

NONSHARABLE_CLASS(MLAPILandmark)

{

public: // New functions

    /**

     * Returns the unique id of this landmark object.

     *

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

     * KLAPINullItemId is returned.

     *

     * The identifier cannot be externally changed. It is modified

     * during the database operations

     *

     * @return The item identifier of this landmark. KLAPINullItemId

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

     */

    virtual TLAPIItemId Id() const = 0;

    /**

     * Sets the name of this landmark.

     *

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

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

     * with KErrArgument

     *

     * @param aName The new name of the landmark.

     */

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

    /**

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

     * if there is no description in this landmark yet

     *

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

     * is read from the native landmark store.

     *

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

     *         landmark does not have a name yet

     */

    virtual const TDesC& NameL() = 0;

    /**

     * Sets the description of this landmark.

     *

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

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

     * ignored

     *

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

     *        NULL argument will remove the existing value when the

     *        landmark is stored again

     */

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

    /**

     * Returns the description of this landmark

     *

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

     * landmark is read from the native landmark store.

     *

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

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

     *         to the caller

     */

    virtual const TDesC* DescriptionL() = 0;

    /**

     * Sets coordinates for this landmark

     *

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

     * an empty TLocality object is used when requesting the position

     * of the landmark

     *

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

     * database values will not be fetched anymore and are overwritten

     * when the item is committed to the native database

     *

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

     *        argument will remove the existing value when then landmark

     *        is stored again

     */

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

    /**

     * Returns the coordinates of this landmark

     *

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

     * an empty TLocality object is used when requesting the position

     *

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

     * landmark are read from the native landmark store.

     *

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

     *         does not have coordinates. The ownership is NOT transferred

     *         to the caller.

     */

    virtual const TLocality* CoordinatesL() = 0;

    /**

     * Sets the address information in this landmark.

     *

     * NULL argument indicates that the address information should

     * be removed from the landmark

     *

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

     *        The ownership is transferred to this class

     */

    virtual void SetAddressInfoL(CLAPIAddressInfo* aAddressInfo) = 0;

    /**

     * Returns the address information for this landmark.

     *

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

     * yet loaded.

     *

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

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

     * subsequently.

     *

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

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

     *         The caller does NOT take the ownership of the object

     */

    virtual const CLAPIAddressInfo* AddressInfoL() = 0;

protected: // Constructor

    /**

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

     */

    virtual ~MLAPILandmark()

    {}

}

;

#endif // MLAPILANDMARK_H

// End of file