diff -r f5050f1da672 -r 04becd199f91 javaextensions/location/landmarks/inc/clapilandmark.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/javaextensions/location/landmarks/inc/clapilandmark.h Tue Apr 27 16:30:29 2010 +0300 @@ -0,0 +1,317 @@ +/* +* 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: Implements a single Location API native landmark + * +*/ + + +#ifndef CLAPILANDMARK_H +#define CLAPILANDMARK_H + +// INTERNAL INCLUDES +#include "mlapilandmark.h" + +// EXTERNAL INCLUDES +#include +#include + +// FORWARD DECLARATIONS +class MLAPILandmarkStore; +class CPosLandmark; + +/** + * Implements a single Location API native landmark + * + * The landmark can have different attributes and address information + * such as name, description, position or country and city information. + * + * A single landmark can be associated to many different categories but + * the categories must defined in the store in which the landmark belongs + * to. The landmark can implicitly belong to many different stores but + * explicitly it can belong to one landmark store at a time. + * + * If the landmark is associated to a store it tries to read its data + * when the data is requested from the object. This optimizes the + * performance of the API in cases where the client does not need to + * display the whole item at once. + * + * @lib N/A + * @since S60 3.2 + */ +NONSHARABLE_CLASS(CLAPILandmark) : public CBase, + public MLAPILandmark +{ +public: // Constructors and destructor + + // Construction parameters of this class + class TCtorParams + { + public: + // The native landmark. NULL indicates that this landmark + // is a new one and not from a landmark store + CPosLandmark* iLandmark; + // The database to which this landmark belongs to. NULL + // indicates that this landmark is a new landmark + MLAPILandmarkStore* iLandmarkStore; + }; + + /** + * Two-phased constructor. Creates an instance from this class + * The caller takes the ownership of the returned instance + * + * @param aParams The construction parameters of this class + * @return New instance from this class + */ + static CLAPILandmark* NewL(const TCtorParams& aParams); + + /** + * Two-phased constructor. Creates an instance from this class + * The caller takes the ownership of the returned instance which + * is left to the cleanup stack + * + * @param aParams The construction parameters of this class + * @return New instance from this class + */ + static CLAPILandmark* NewLC(const TCtorParams& aParams); + + /** + * Destructor. + */ + virtual ~CLAPILandmark(); + +public: // From MLAPILandmark + + /** + * Returns the unique id of this landmark object. + * + * If 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 + */ + TLAPIItemId Id() const; + + /** + * 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. + */ + void SetNameL(const TDesC& aName); + + /** + * 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 + */ + const TDesC& NameL(); + + /** + * 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 + */ + void SetDescriptionL(const TDesC* aDescription); + + /** + * 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 + */ + const TDesC* DescriptionL(); + + /** + * 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 + */ + void SetCoordinatesL(const TLocality* aCoordinates); + + /** + * 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. + */ + const TLocality* CoordinatesL(); + + /** + * 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 + */ + void SetAddressInfoL(CLAPIAddressInfo* aAddressInfo); + + /** + * 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 + */ + const CLAPIAddressInfo* AddressInfoL(); + +public: // New functions + + /** + * Prepares the item for saving. This operation must be called + * always when the item is to be persisted to some existing database + * It guarantees that the data which has been modified is correctly + * written and stored to the native database so, in practice, this + * operation commits the changes made to the item after previous + * call of PrepareForSaveL + * + * Note that at this point, any existing data will be overwritten + * and the full item is loaded from the landmark store so this + * should be used with caution and only when the item is to be + * fully saved to a database or exported to some external module + */ + void PrepareForSaveL(); + + /** + * Returns the native counterpart of this class. Note that + * the object may not be up to date if PrepareForSaveL() has + * not been called + * @return Landmarks API landmark implementation + */ + CPosLandmark& PosLandmark() const; + + /** + * Sets new CPosLandmark object to this landmark. The existing + * object will be replaced. The ownership is transferred to + * this class. + * + * @param aLandmark New CPosLandmark object + */ + void SetPosLandmark(CPosLandmark* aLandmark); + + /** + * Associates this landmark to a landmark store.. The landmark can + * belong to one landmark store at a time. If the landmark is transferred + * to a different store, the old store will be notified + * + * @param aStore The store where this landmark has been added + */ + void AssociateToStore(MLAPILandmarkStore* aStore); + + /** + * Indicates that the store in which this landmark belongs to + * has been closed + */ + void StoreClosed(); + +private: // New functions + + /** + * Read address information values from the native CPosLandmark + * object owned by this class. + * + * The values are read to iAddressInfo which must not be null. + * Otherwise this function will panic + * + * @param aPositionFields The position fields which should be read + * from the native CPosLandmark object + * @return The number of available position fields in the native + * landmark + */ + TInt DoGetAddressInfoFieldValuesL(const RArray< TUint>& aPositionFields); + +private: // Constructors + + /** + * Constructor + * @param aParams The constructions parameters of this class + */ + CLAPILandmark(const TCtorParams& aParams); + + /** + * Second phase constructor + */ + void ConstructL(); + +private: // Data + + // The landmark store to which this landmark belongs. Used. Can be NULL + MLAPILandmarkStore* iLandmarkStore; + // Associated native landmark object. Owned + CPosLandmark* iLandmark; + + // The name of the landmark. Owned + HBufC* iLandmarkName; + // The description of the landmark. Owned + HBufC* iDescription; + // Coordinates fo the landmark. Owned + TLocality* iCoordinates; + // Address information. Owned + CLAPIAddressInfo* iAddressInfo; + + // Attributes of this landmark. This marks the landmark attributes + // which are changed during the lifetime of the landmark. + TUint iChangedAttributes; + +}; + +#endif // CLAPILANDMARK_H +// End of file