diff -r e8e63152f320 -r 2a9601315dfc javaextensions/location/landmarks/inc/mlapilandmark.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/javaextensions/location/landmarks/inc/mlapilandmark.h Mon May 03 12:27:20 2010 +0300 @@ -0,0 +1,238 @@ +/* +* 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 + +// 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