/*

* Copyright (c) 2005-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:  CMnGeocoder class

*

*/

#ifndef MN_GEOCODER_H

#define MN_GEOCODER_H

#include <e32base.h>

class CApaServerAppExitMonitor;

class MAknServerAppExitObserver;

class CMnProvider;

class CPosLandmark;

class RMnGeocodingServiceClient;

/** @brief Provides access to geocoding features.

 *

 *  Both geocoding (address to coordinate) and "reverse geocoding"

 *  (coordinate to address) features are provided by this class. Further in

 *  documentation they are all referred to as "geocoding" if not specified otherwise.

 *

 *  Geocoding operations are asynchronous, they can be cancelled by @ref Cancel().

 *  However only one asynchronous request can be issued at a time, otherwise client

 *  will be panicked with KMnPanicDuplicateRequest.

 *

 *  To create an instance of the class, use @ref NewL or @ref NewChainedL methods. They

 *  require an instance of CMnProvider, defined in Map and Navigation Provider Discovery API.

 *

 *  Main methods are @ref FindCoordinateByAddressL (two overloads) and

 *  @ref FindAddressByCoordinateL.

 *  Other methods define optional information that changes behavior of the

 *  class and others help to retrieve results of main methods' execution.

 *

 *  @since 3.1

 *  @lib mnclientlib.dll

 *  @ingroup MnGeocodingAPI

 */

class CMnGeocoder : public CBase

    {

    public :

        /** Type for bitmap of @ref TOption values. */

        typedef TUint32 TOptions;

        /** @brief Options defining geocoding execution. */

        enum TOption

            {

            /** Default value */

            EOptionNone           = 0x00,

            /** Defines that no queries to user are allowed during

             *  geocoding operations */

            EOptionDialogDisabled = 0x01

            };

        /** Destructor */

        IMPORT_C ~CMnGeocoder();

        /** @brief Creates new instance of the class. Provider Application

         *  will be executed standalone.

         *

         *  @param[in] aProvider Provider Application to be used for geocoding.

         *  @return Pointer to new instance of the class.

         *

         *  @leave KErrNotSupported Selected Provider Application does not support

         *      @ref CMnProvider::EServiceGeocoding.

         */

        IMPORT_C static CMnGeocoder* NewL( CMnProvider& aProvider );

        /** @brief Creates new instance of the class. Provider Application

         *  will be executed chained (unless Provider Application defines that

         *  it should be started in background).

         *

         *  @param[in] aProvider Provider Application to be used for geocoding.

         *  @return Pointer to new instance of the class.

         *

         *  @leave KErrNotSupported Selected Provider Application does not support

         *      @ref CMnProvider::EServiceGeocoding.

         */

        IMPORT_C static CMnGeocoder* NewChainedL( CMnProvider& aProvider );

        /** @brief Retrieves current geocoding options.

         *  @return Bitmap of @ref TOption values.

         */

        IMPORT_C TOptions Options() const;

        /** @brief Sets geocoding options.

         *  @param aOptions Bitmap of @ref TOption values.

         */

        IMPORT_C void SetOptions( TOptions aOptions );

        /** @brief Retrieves result of last geocoding or reverse geocoding operation.

         *

         *  If last operation result was address then address information in the

         *  passed landmark is updated. If last operation result were coordinates,

         *  then coordinate information of the landmark is updated.

         *  Note that landmark is not stored in any database, client has to do it

         *  itself if needed.

         *

         *  Target landmark parameter does not have to be a different landmark then that

         *  was passed for geocoding or reverse geocoding. However, all address

         *  or coordinate (depending on last operation result type) information

         *  will be updated in target landmark.

         *

         *  Issuing next geocoding request discards current result.

         *

         *  @param[out] aTargetLandmark This landmark will be updated according to

         *                         last operation result.

         *

         *  @leave KErrNotFound Result is not available.

         */

        IMPORT_C void RetrieveGeocodingResultL( CPosLandmark& aTargetLandmark );

        /** @brief Initiates geocoding: translating street address to coordinates.

         *

         *  Address information from passed landmark will be used.

         *

         *  Only one coordinate will be the result of this operation.

         *  If any ambiguities arise during translation, then Provider Application

         *  may query the user to solve it. Set EOptionDialogDisabled to prevent this.

         *

         *  Use RetrieveGeocodingResultL() to retrieve results of the operation.

         *

         *  This method can leave in case of memory lack or other system error.

         *  If it leaves, no asynchronous request is outstanding.

         *

         *  @param[in] aLandmark Landmark containing address information

         *  @param[out] aRequest Contains result of the request, when it is completed.

         *      @p KErrNotFound if given address couldn't be resolved to coordinate

         *      (also due to disabling of query dialog). @p KErrCancel, if user has cancelled

         *      the operation. @p KErrArgument, if input landmark does not contain address

         *      information. @p KErrNone if request is completed successfully.

         *

         *  @panic "MnClientPanic"-KMnPanicDuplicateRequest New asynchronous request

         *          is issued before previous one is completed.

         */

        IMPORT_C void FindCoordinateByAddressL(

            const CPosLandmark& aLandmark,

            TRequestStatus& aRequest );

        /** @brief Initiates geocoding: translating street address to coordinates.

         *

         *  This is the another overload, which accepts address input as plain

         *  string.

         *

         *  Only one coordinate will be the result of this operation.

         *  If any ambiguities arise during translation, then Provider Application

         *  may query the user to solve it. Set EOptionDialogDisabled to prevent this.

         *

         *  Use RetrieveGeocodingResultL() to retrieve results of the operation.

         *

         *  This method can leave in case of memory lack or other system error.

         *  If it leaves, no asynchronous request is outstanding.

         *

         *  @param[in] aAddress Plain address. Format of this string is not defined,

         *                  this is barely how human user writes addresses down.

         *  @param[out] aRequest Contains result of the request, when it is completed.

         *      @p KErrNotFound if given address couldn't be resolved to coordinate

         *      (also due to disabling of query dialog). @p KErrCancel, if user has cancelled

         *      the operation. @p KErrNone if request is completed successfully.

         *

         *  @panic "MnClientPanic"-KMnPanicDuplicateRequest New asynchronous request

         *          is issued before previous one is completed.

         */

        IMPORT_C void FindCoordinateByAddressL(

            const TDesC& aAddress,

            TRequestStatus& aRequest );

        /** @brief Initiates reverse geocoding: translating coordinates to

         *  street address.

         *

         *  Coordinate information from passed

         *  landmark will be used. Any other helper information (like coverage

         *  radius, existing address information) can also be used. If it is not

         *  desired, then this information should be removed from landmark

         *  by client.

         *

         *  Only one address will be the result of this operation.

         *  If any ambiguities arise during translation, then Provider Application

         *  may query user to solve it. Set EOptionDialogDisabled to prevent this.

         *  Additional information (other than coordinate) found in landmark cannot

         *  be a reason for such a request.

         *

         *  Use RetrieveGeocodingResultL() to retrieve results of the operation.

         *

         *  This method can leave in case of memory lack or other system error.

         *  If it leaves, no asynchronous request is outstanding.

         *  @param[in] aLandmark Landmark containing address information

         *  @param[out] aRequest Contains result of the request, when it is completed.

         *      @p KErrNotFound if given address couldn't be resolved to coordinate

         *      (also due to disabling of query dialog). @p KErrCancel, if user has cancelled

         *      the operation. KErrArgument, if input landmark does not contain coordinate

         *      information (latitude and longitude are required).

         *      @p KErrNone if request is completed successfully.

         *

         *  @panic "MnClientPanic"-KMnPanicDuplicateRequest New asynchronous request

         *          is issued before previous one is completed.

         */

        IMPORT_C void FindAddressByCoordinateL(

            const CPosLandmark& aLandmark,

            TRequestStatus& aRequest );

        /** @brief Cancels current outstanding asynchronous request. */

        IMPORT_C void Cancel();

        /** @brief Sets observer of provider application lifetime.

         * 	Client will receive exit event from provider application.

         *  By default exit events from provider application are not monitored.

         *  @param[in] aObserver Exit observer.

         *  @leave KErrAlreadyExists if observer is already set. 

         */

        IMPORT_C void SetExitObserverL( MAknServerAppExitObserver& aObserver );

        /** @brief Removes observer of provider application lifetime. */

        IMPORT_C void RemoveExitObserver();

    private :

        /** C++ constructor */

        CMnGeocoder();

        void ConstructCommonL( CMnProvider& aProvider );

        void ConstructNewL( CMnProvider& aProvider );

        void ConstructChainedL( CMnProvider& aProvider );

    private :

        TOptions iOptions;

        RMnGeocodingServiceClient* iSession;

        CApaServerAppExitMonitor* iExitMonitor;

    };

#endif // MN_GEOCODER_H