/*

* 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    <e32base.h>

#include    <lbsposition.h>

// 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