/*
* Copyright (c) 2006 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:  CMnrpEngine class definition
*
*/


#ifndef MNRP_ENGINE_H
#define MNRP_ENGINE_H

#include <e32base.h>
#include <f32file.h>

class CPosLandmark;
class TCoordinate;
class RResourceReader;

/** Engine class used both by MnRefProvider and MnRefGeocoder 
 *	components. Provides access to POIs database ( resource file,
 *	some cities ) and geocoding services. 
 */
class CMnrpEngine : public CBase
    {
    public:
    
        struct TDistanceToPoi
            {
            TInt iPoiIndex; // index to KnownPlaces
            TReal32 iDistance; // distance to Poi of iPoiIndex
            };
    
    public:
        IMPORT_C static CMnrpEngine* NewL();
        IMPORT_C ~CMnrpEngine();

		/** Gives access to set of POIs */
        IMPORT_C TArray<CPosLandmark*> KnownPlacesL();
        
        /** Returns coordinate of given address:
		 *	Find a POI, which country or city matches given address
		 *	and returns its coordinates.
		 *	@param aAddress landmark, containing address
		 *	@return landmark, containg coordinates
		 *	@leave KErrNotFound if can't find POI matching given address
 		 */
        IMPORT_C CPosLandmark* AddressToCoordLC( const CPosLandmark& aAddress );

        /** @overload
         *  @return landmark, containg coordinates, or NULL
         */
        IMPORT_C CPosLandmark* AddressToCoordL( const CPosLandmark& aAddress );
        
        /** @overload
		 *	@param aAddress string containing address
		 *	@return landmark, containg coordinates
		 *	@leave KErrNotFound if can't find POI matching given address
 		 */
        IMPORT_C CPosLandmark* AddressToCoordLC( const TDesC& aAddress );

        /** @overload
         *  @param aAddress string containing address
         *  @return landmark, containg coordinates, or NULL
         */
        IMPORT_C CPosLandmark* AddressToCoordL( const TDesC& aAddress );

        /** Returns address for given coordinate:
		 *	Find a closest POI and return its city and country and
 		 *	fill street with "%d[m,Km,tKm] from <city>" string, like "5 km to Tampere"
		 *	@param aLocation coordinate
		 *	@return landmark, containg address
		 *	@leave KErrNotFound if can't find any POI
 		 */
        IMPORT_C CPosLandmark* CoordToAddressLC( const TCoordinate& aLocation );
        
        /** Finds a resource file in the system. 
         *	It looks on all the drives for the file and folder given as parameter
         *	@param[in] aFilePathAndName path and name of the file to search for. Drive
         *							info is ignored
         *	@param[out] aRscFile full name of found resource file
         *	@leave KErrNotFound if file is not found.
         */
        IMPORT_C void FindResourceFileL( 
            const TDesC& aFilePathAndName,
            TFileName& aRscFile );

        /** Returns reference to open file session, given at construction */
        IMPORT_C RFs& Fs();

        /** Calculates distance between two landmarks.
         *  @param aFrom Source landmark
         *  @param aTo Destination landmark
         *  @return Distance, or NaN, if distance cannot be calculated
         */
        IMPORT_C TReal32 DistanceBetweenLandmarks( 
            const CPosLandmark& aFrom, 
            const CPosLandmark& aTo );

        /** Finds POIs closest to given reference landmark. 
         *  @param[in] aReference reference landmark
         *  @param[out] aNeighbourPois List of closest POIs. 
         *  @param[in] aMaxMatches Maximum number of results needed
         */
        IMPORT_C void FindClosestPoisL( 
            const CPosLandmark& aReference,
            RArray<CMnrpEngine::TDistanceToPoi>& aNeighbourPois,
            TInt aMaxMatches );

        /** Finds POIs closest to given location. 
         *  @param[in] aReference reference location
         *  @param[out] aNeighbourPois List of landmarks of closest POIs. 
         *  @param[in] aMaxMatches Maximum number of results needed
         */
        IMPORT_C void BestCoordToAddressMatchesL( 
            const TCoordinate& aLocation,
            RPointerArray<CPosLandmark>& aMatches,
            TInt aMaxMatches );

    protected:

        void ConstructL();
        CMnrpEngine();

		/** Loads POIs from database ( resource file ) */
        void LoadKnownPlacesL();
        /** Reads array of PLACES resource structures */
        void ReadPlacesResourceL( RResourceReader& aReader );
        
        CPosLandmark* CreateCloseLandmarkLC( const CPosLandmark& aReference, TReal32 aDistance );

    private:
        RPointerArray<CPosLandmark> iPlaces;
        RFs                         iFileSession;
    };

#endif // MNRP_ENGINE_H