/*
* 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 the native part of the Location API landmark store
 *
*/


#ifndef CLAPILANDMARKSTORE_H
#define CLAPILANDMARKSTORE_H

// INTERNAL INCLUDES
#include    "mlapilandmarkstore.h"
#include    "mlapilmdatabaseobserver.h"
#include    "mlapilandmark.h"

// EXTERNAL INCLUDES
#include    <e32def.h>
#include    <e32base.h>
#include    <EPos_Landmarks.h>

// FORWARD DECLARATIONS
class CLAPILandmarkSearchFactory;
class TLAPISearchCriteria;
class CPosLandmarkDatabase;
class CPosLandmark;
class MLAPICategoryManager;
class MLAPILmDatabaseEventNotifier;

/**
 * Implements the native part of Location API landmark store.
 *
 * This class provides the basic functionalities for handling
 * individual landmarks such as adding, deleting and updating landmarks
 *
 * The stores are available always when it once has been opened. This
 * is because some items may still exists in the java side after the
 * store has been closed. Function calls to a closed store leaves with
 * KErrSessionClosed. The stores cannot be closed explicitly from the Java
 * but only when a store is deleted from the device
 *
 * Ensuring that stores are not always open prevents the API to reserve
 * huge amount of memory if many stores are used concurrently
 *
 * @lib N/A
 * @since S60 3.2
 */
NONSHARABLE_CLASS(CLAPILandmarkStore) : public CBase,
        public MLAPILandmarkStore
{
public: // Type definitions

    // Construction parameters of this class
    class TCtorParams
    {
    public:
        // The ownership of these are transferred in the construction
        CPosLandmarkDatabase* iLandmarkDatabase;
        MLAPICategoryManager* iCategoryManager;
        MLAPILmDatabaseEventNotifier* iEventNotifier;
    };

public: // Constructors and destructor

    /**
     * Two-phased constructor. Creates an instance from this class
     * The caller takes the ownership of the returned instance
     *
     * @param aParams Construction parameters of this class
     * @return New instance from this class
     */
    static CLAPILandmarkStore* 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 Construction parameters of this class
     * @return New instance from this class
     */
    static CLAPILandmarkStore* NewLC(const TCtorParams& aParams);

    /**
     * Destructor.
     */
    virtual ~CLAPILandmarkStore();

public: // From MLAPILandmarkStore

    /**
     * Reads the full landmark data from the database. The data
     * is added to the item which is passed as a parameter. Note
     * that this function may be time consuming if it is called
     * for huge amount of landmarks subsequently.
     *
     * The function should only be used when the item is needed
     * to be fully writen into the native database. The operation
     *
     * @param aLandmark The landmark which will be read from the database
     */
    void ReadFullLandmarkL(CLAPILandmark& aLandmark);

    /**
     * Reads the requested attributes to a landmark from the native database.
     * It also possible to read certain position fields from the native
     * database.
     *
     * @param aLandmark The landmark which is to be read
     * @param aAttributes The attributes which are read
     * @param aAddressInfos The requested address info fields which
     *        are read from the native database. If this parameter is
     *        NULL, then no position fields are read. Note that the
     *        ownership of the array does NOT transfer to this class
     */
    void ReadLandmarkAttributesL(
        CLAPILandmark& aLandmark,
        const TUint aAttributes,
        const RArray< TUint>* aAddressInfos);

    /**
     * Returns the category manager for this database. If NULL is returned
     * this database does not support categories at all.
     *
     * @return Category manager for this landmark store. The ownership is
     *         NOT transferred to the caller. NULL indicates that the store
     *         does not support category management
     */
    MLAPICategoryManager* CategoryManagerL() const;

    /**
     * Indicates that a landmark is going to be disposed. This removes
     * any possible references to the landmark from this store if the
     * landmark belongs to the store
     *
     * @param aLandmark A references to the disposed landmark object
     */
    void LandmarkDisposed(CLAPILandmark& aLandmark);

public: // New functions

    /**
     * Returns the URI of this landmark store
     * @return The URI of the landmark store
     */
    const TDesC& StoreUri() const;

    /**
     * Returns an array of landmarks based on the search attributes and
     * initialization parameters. The caller takes the ownership of the
     * returned array.
     *
     * Currently it is possible to search using three different parameters
     * and additionally a different mixture of these parameters. If no
     * criteria is specified, all landmarks in the store will be returned
     *
     *      - A text with attributes can be specified to perform a search
     *        from every string field in a landmark
     *      - A category name can be specified to perform a search from
     *        the specified category
     *      - An area can be specified to perform an area specific search
     *
     * @param aAttributes The attributes which will be pre-initialized
     *        to the matched landmarks. Note that initializing time depends
     *        on the number of initialized attributes
     * @param aSearchCriteria The search criteria which is used to search
     *        the landmarks. NULL matches all landmarks
     * @return An array of landmark. The caller takes the ownership of the
     *         array and the landmarks in it
     */
    CArrayPtr< CLAPILandmark>* LandmarksL(
        const TUint aAttributes,
        const TLAPISearchCriteria* aSearchCriteria);

    /**
     * Adds a new landmark to this landmark store. If the landmark already
     * belongs to this store nothing happens
     *
     * @param aLandmark The landmark which will be added
     */
    void AddLandmarkL(CLAPILandmark& aLandmark);

    /**
     * Updates an existing landmark in the database. The data is copied
     * from aLandmark object and added to the existing landmark in the
     * database.
     *
     * This operation leaves with KErrNotFound if there is no such landmark
     * in the database
     *
     * @param aLandmark The landmark which will be updated
     */
    void UpdateLandmarkL(CLAPILandmark& aLandmark);

    /**
     * Removes an existing landmark from this landmark store
     *
     * The call is silently ignored if the landmark does not belong to this
     * store or if it has already been removed.
     *
     * @param aLandmark The landmark which is to be removed
     */
    void RemoveLandmarkL(CLAPILandmark& aLandmark);

    /**
     * Compacts the native database if it is necessary.
     *
     * The compacting is done synchronously so it may take some time to complete
     * depending on the number of the landmarks and categories which
     * are stored to this landmark store
     */
    void CompactIfNeededL();

    /**
     * Closes this landmark store. Note that this does not delete
     * this object but only closes the access to the native database
     * The object is still usable, but invocations will leave with
     * KErrSessionClosed.
     *
     * Stores can be closed internally when the object needs to be
     * deleted or externally when the store is needed to be closed
     * due to, for example, database deletion.
     */
    void Close();

private: // New functions

    /**
     * Converts prepared landmarks to Location API landmarks
     * Note that this is only needed because of the cleanup problems
     * related to ownership transferring of CArrayPtr which comes
     * from Landmarks API
     *
     * @param aSrcArray The array from which the objects are created
     *        on return, the array is empty
     * @param aDestArray The array to which the new landmarks are added
     */
    void HandlePreparedLandmarksL(
        CArrayPtr< CPosLandmark>& aSrcArray,
        CArrayPtr< CLAPILandmark>& aDestArray);

    /**
     * Refreshes all landmarks which match for the given identifier.
     * Note that this operation may be a very huge operation if one
     * landmark has many references from the Java side
     *
     * @param aLandmarkId The identifier of updated landmarks
     * @param aRemoveFromStore Indicates that the refreshed landmarks
     *        should be removed from this landmark store. By default,
     *        the landmarks are not removed
     */
    void RefreshLandmarksL(
        TLAPIItemId aLandmarkId,
        TBool aRemoveFromStore = EFalse);

private: // Construtors

    /**
     * C++ constructor.
     * @param aParams Construction parameters
     */
    CLAPILandmarkStore(const TCtorParams& aParams);

    /**
     * Second phase constructor
     */
    void ConstructL();

private: // Data

    // All landmark objects. Used
    RPointerArray< CLAPILandmark> iLandmarks;

    // Landmark database. Owned
    CPosLandmarkDatabase* iLandmarkDatabase;

    // Category manager. Owned
    MLAPICategoryManager* iCategoryManager;

    // Database event notifier. Owned
    MLAPILmDatabaseEventNotifier* iEventNotifier;

    // Landmark search factory. Owned
    CLAPILandmarkSearchFactory* iSearchFactory;

    // The URI of this store. Owned
    HBufC* iStoreUri;
};

#endif // CLAPILANDMARKSTORE_H
// End of file