/*

* Copyright (c) 2007 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:  Location Centre API interface.

*

*/

/**

 *  @file lcservice.h

 *

 *  This file provides the interface class to Location Centre. Using this interface

 *  the client application can operate upon components which have registered with

 *  Location Centre.

 *  The components which can register with Location Centre are of two types

 *  - Applications

 *  - Location based services / contents.

 *

 *  These Client Applications or Services/Contents which register with Location

 *  Centre will be called Location based Application henceforth.

 *

 *  @lib lcservice.lib

 *  @since S60 v5.0

 */

#ifndef C_LCSERVICE_H

#define C_LCSERVICE_H

// SYSTEM INCLUDES

#include <e32base.h>

// USER INCLUDES

#include "lclocationappinfo.h"

// FORWARD DECLARATIONS

class CLcServiceImpl;

class MLcAppExitObserver;

class MLcNotification;

class TLcLocationAppFilter;

/**

 *  @class CLcService

 *  Interface to Location Centre.

 *

 *  This class allows the Client application to incorporate Location Centre

 *  and Location Centre related functionalities into their application.

 *  The following are the functionalities exposed by this API.

 *

 *  - Get the list of Location based Applications registered with Location Centre.

 *

 *  - Launch Location Centre with a customized set of Location based Application.

 *

 *  - Launch a particular Location based Application.

 *

 *  - Register for notification of changes to the state of the Location

 *    based Applications.

 *

 *  In additon to the above functions, the user can also customize the list

 *  of Location based Applications using the @ref TLcLocationAppFilter filter.

 *

 *  Since, this class acts as a Client side interface to the Location Centre

 *  server, it is recommended that the Client application creates the

 *  instance of this class during its construction and delete it only on

 *  Exit.

 *  @lib lcservice.lib

 *  @since S60 v5.0

 */

class CLcService : public CBase

    {

public:

    /**

     * @class CLcLaunchParam

     * Contains additional parameters for customized Location Centre

     * launching. It specifies the Location based Application that needs to be

     * displayed in Location Centre and the mode of launching for each of

     * these Location based Application when a User selects any of them. This

     * array of these structures is to be passed as an input to the 

     * overloaded @ref LaunchLocationCentreL function

     */

    class CLcLaunchParam : public CBase

        {

        public:

            /**

             * Constructs a new instance of Launch parameter object.

             *

             * @since S60 v5.0              

             * @param[in] aAppId        Identifier for the Location based Application.

             *                          The identifier string is copied.

             * @param[in] aLaunchMode   Launch mode when the terminal user selects

             *                          this Location based Application. The values

             *                          which this parameter can assume is defined

             *                          by the @ref CLcLocationAppInfo::TLcLaunchMode

             *                          enumeration.

             *                          If the user doesn't define a value for this

             *                          parameter then @ref CLcLocationAppInfo::EDefaultMode

             *                          is assumed. 

             * @return The new instance of Launch parameter object.

             * @leave System wide error code if the object creation fails.         

             */        

            IMPORT_C static CLcLaunchParam* NewL

                ( const TDesC&     aAppId,

                        CLcLocationAppInfo::TLcLaunchMode aLaunchMode = 

                                                CLcLocationAppInfo::EDefaultMode );

            /**

             * Constructs a new instance of Launch parameters object.

             * Leaves the created instance on the cleanup stack.

             *

             * @since S60 v5.0             

             * @param[in] aAppId        Identifier for the Location based Application.

             *                          The identifier string is copied.             

             * @param[in] aLaunchMode   Launch mode when the terminal user selects

             *                          this Location based Application. The values

             *                          which this parameter can assume is defined

             *                          by the @ref CLcLocationAppInfo::TLcLaunchMode

             *                          enumeration.

             *                          If the user doesn't define a value for this

             *                          parameter then @ref CLcLocationAppInfo::EDefaultMode

             *                          is assumed. 

             * @return The new instance of Launch parameter object.

             * @leave System wide error code if the object creation fails.         

             */                                                

            IMPORT_C static CLcLaunchParam* NewLC

                ( const TDesC&     aAppId,

                        CLcLocationAppInfo::TLcLaunchMode aLaunchMode = 

                                                CLcLocationAppInfo::EDefaultMode );

            /**

             * Virtual Destructor

             */

            virtual ~CLcLaunchParam();

       	public: // Non Exported Methods                 

            /**

             * @internal 

             * Gets the Unique identifier identifying the Location Application.

             * This identifier is defined by the Location Application on registration

             * with Location Centre.

             * This is the identifier that must be used by the client of this API for 

             * any operation on the particular Location Application.

             * A reference to the object's internal string is returned.     

             *

             * @since S60 v5.0     

             * @return Unique identifier identifying the Location Application. If the

             *         value of the identifier has not been set then a NULL string

             *         is returned.

             */                                   

            TPtrC  Id() const;

            /**

             * @internal

             * Mode in which the Location Application would be launched. 

             * If the mode defined is @ref CLcLocationAppInfo::EDefaultMode, then

             * the default mode specified by the application when registering with

             * Location Centre is used.

             *

             * @since S60 v5.0     

             * @return Mode in which the Location Application would be launched.       

             */            

            CLcLocationAppInfo::TLcLaunchMode  LaunchMode() const;

        private:

        	/**

        	 * C++ Default Constructor

        	 */

        	CLcLaunchParam( CLcLocationAppInfo::TLcLaunchMode aLaunchMode );

        	/**

        	 * Second phase of the Symbian two phase construction.

        	 */

        	void ConstructL( const TDesC& 	aAppId );        	

        private:

	        /**

	         * System wide unique identifier identifying the Location based

	         * Application. This identifier is defined by the Location based

	         * Application on registration with Location Centre.

	         * Owns

	         */               

	        HBufC*                               iId;

	        /**

	         * Mode in which the Location based Application would be launched. If

	         * the mode defined is @ref CLcLocationAppInfo::EDefaultMode, then

	         * the mode specified by the Location based Application when

	         * registering with Location Centre is used.

	         * If no value is specified for this paramter then it takes 

	         * @ref CLcLocationAppInfo::EDefaultMode as its value.

	         */            

	        CLcLocationAppInfo::TLcLaunchMode     iLaunchMode;

        };

public: // Exported Functions

    /**

     * Constructs a new instance of Location Centre interface.

     *

     * @return The new instance of Location Centre interface object.

     * @leave System wide error code if the object creation fails.         

     */

    IMPORT_C static CLcService* NewL();

    /**

     * Constructs a new instance of Location Centre interface.

     * Leaves the created instance on the cleanup stack.

     *

     * @return The new instance of Location Centre interface object.

     * @leave System wide error code if the object creation fails.         

     */

    IMPORT_C static CLcService* NewLC();        

    /**

     * C++ Destructor.

     * Frees all the resources associated with this Location Centre

     * interface.

     */

    virtual ~CLcService();

    /**

     * Launches Location Centre as a pop-up dialog with a list of

     * Location based Application.

     *

     * All Location based Applications which can be launched in the

     * specified mode are displayed in the Location Centre pop-up

     * dialog. The user can select any of the Location based

     * Applications displayed in the pop-up list and the

     * corresponding Location based Application would be launched

     * in the specified launching mode.

     *

     * @since S60 v5.0      

     * @param [in] aLaunchMode Mode in which the the Location based

     *                         Applications displayed in the pop-up

     *                         must be launched. The default mode for

     *                         launching is the mode in which the

     *                         corresponding Location based Application 

     *                         has registered with Location Centre.       

     * @param[in] aChainedAppExitObserver Observer for notifications of

     *                                    chained application termination

     *                                    incase, the user launches any

     *                                    Location based Application from the

     *                                    pop-up in the chained mode. If

     *                                    the user doesn't specify any value

     *                                    for the observer then no callback

     *                                    would be given on chained

     *                                    application termination.

     * @leave KErrInUse - If there is an outstanding request present on Location Centre.     

     * @leave KErrNotFound - If no Location based Applications were found

     *                       with the required configuration.

     * @leave KErrNotSupported - If Location Centre cannot be launched. This

     *                           generally occurs when the Client application

     *                           does not have a UI context.

     * @leave KErrServerTerminated - If the Location Centre server terminates

     *                               prematurely. In this case, all future

     *                               requests to Location Centre would also

     *                               fail with the same error code.

     * @leave System wide error code if the operation fails due to some other

     *        reason.

     */                        

    IMPORT_C void LaunchLocationCentreL(

        CLcLocationAppInfo::TLcLaunchMode   aLaunchMode = CLcLocationAppInfo::EDefaultMode,

        MLcAppExitObserver*                 aChainedAppExitObserver = NULL );

    /**

     * Launches Location Centre as a pop-up dialog with a filtered list of

     * Location based Application.

     *

     * The Client application can configure Location Centre to display 

     * only a subset of Location based Applications. This can be achieved

     * by passing an object of type @ref TLcLocationAppFilter as the

     * parameter to this function. Only those Location based Applications

     * which satisfy the filter conditions and can be launched in the 

     * specified mode are displayed in Location Centre. 

     * The user can select any of the Location based Applications displayed

     * in the pop-up list and the  Location based Application would be

     * launched in the specified launching mode.

     *

     * The ownership of the filter is not transferred to Location Centre.        

     *

     * @since S60 v5.0      

     * @param[in] aLocationAppFilter Filter that needs to be applied 

     *                               to customize the list of Location

     *                               based Applications to be displayed in

     *                               Location Centre.

     * @param [in] aLaunchMode Mode in which the the Location based

     *                         Applications displayed in the pop-up

     *                         must be launched. The default mode for

     *                         launching is the mode in which the

     *                         corresponding Location based application has

     *                         registered with Location Centre.         

     * @param[in] aChainedAppExitObserver Observer for notifications of

     *                                    chained application termination

     *                                    incase, the user launches any

     *                                    Location based Application from the

     *                                    pop-up in the chained mode. Incase,

     *                                    the user doesn't specify any value

     *                                    for the observer then no callback

     *                                    would be given on ahained

     *                                    application termination.

     * @leave KErrInUse - If there is an outstanding request present on Location Centre.     

     * @leave KErrNotFound - If no Location based Applications were found

     *                       with the required configuration.

     * @leave KErrNotSupported - If Location Centre cannot be launched. This

     *                           generally occurs when the Client application

     *                           does not have a UI context.

     * @leave KErrServerTerminated - If the Location Centre server terminates

     *                               prematurely. In this case, all future

     *                               requests to Location Centre would also

     *                               fail with the same error code.     

     * @leave System wide error code if the operation fails due to some other

     *        reason.

     */                        

    IMPORT_C void LaunchLocationCentreL( 

        const TLcLocationAppFilter&         aLocationAppFilter,

        CLcLocationAppInfo::TLcLaunchMode   aLaunchMode = CLcLocationAppInfo::EDefaultMode,

        MLcAppExitObserver*                 aChainedAppExitObserver = NULL );

    /**

     * Launches Location Centre with the specified array of Location

     * based Applications in a pop-up dialog.

     *

     * The items of the array are first validated for their registration

     * with Location Centre and only those Location based Applications which are

     * registered with Location Centre and which can be launched in the

     * specified launch mode are displayed.

     * The user can select any of the Location based Application displayed in the 

     * pop-up list and the corresponding Location based Application would be opened

     * the mode defined in the corresponding @ref TLcLaunchParam

     * object.

     *

     * The ownership of the specified array is not tranferred to Location

     * Centre.

     *

     * @since S60 v5.0         

     * @param[in] aIncludeAppArray  Array of Location based Applications which

     *                              are to be displayed in Location Centre.

     * @param[in] aChainedAppExitObserver Observer for notifications of

     *                                    chained application termination

     *                                    incase, the user launches any

     *                                    Location based Application from the

     *                                    pop-up in the chained mode. Incase,

     *                                    the user doesn't specify any value

     *                                    for the observer then no callback

     *                                    would be given on chained

     *                                    application termination.

     * @leave KErrInUse - If there is an outstanding request present on Location Centre.     

     * @leave KErrNotFound - If none of the specified Location based

     *                       Applications were found registered with 

     *                       Location Centre.

     * @leave KErrNotSupported - If Location Centre cannot be launched. This

     *                           generally occurs when the Client application

     *                           does not have a UI context.

     * @leave KErrServerTerminated - If the Location Centre server terminates

     *                               prematurely. In this case, all future

     *                               requests to Location Centre would also

     *                               fail with the same error code.     

     * @leave System wide error code if the operation fails due to some other

     *        reason.

     */                        

    IMPORT_C void LaunchLocationCentreL(

                  const RPointerArray<CLcLaunchParam>& aIncludeAppArray,

                  MLcAppExitObserver*                  aChainedAppExitObserver = NULL );

    /**

     * Launches Location Centre without the specified array of

     * Location based Applications in a pop-up dialog.

     *

     * Only those Location based Applications which are not a part of the

     * specified array and which can be launched in the specified mode

     * are displayed in Location Centre. 

     * The user can select any of the Location based Application displayed in the 

     * pop-up list and the corresponding Location based Application would be opened

     * the mode defined in the specified mode.

     *

     * The ownership of the specified array is not tranferred to Location

     * Centre.

     *

     * @since S60 v5.0     

     * @param[in] aExcludeAppArray Array of identifiers of Location based

     *                             Application which are not to be displayed

     *                             in Location Centre.

     *                             These identifiers are to be defined by the

     *                             Location based Application on registration with

     *                             Location Centre.

     * @param [in] aLaunchMode Mode in which the all the Location

     *                         applications displayed in the pop-up

     *                         must be launched. The default mode for

     *                         launching is the mode in which the

     *                         corresponding application has registered

     *                         with Location Centre.         

     * @param[in] aChainedAppExitObserver Observer for notifications of

     *                                    chained application termination

     *                                    incase, the user launches any

     *                                    Location based Application from the

     *                                    pop-up in the chained mode. Incase,

     *                                    the user doesn't specify any value

     *                                    for the observer then no callback

     *                                    would be given on chained

     *                                    application termination.

     * @leave KErrInUse - If there is an outstanding request present on Location Centre.     

     * @leave KErrNotFound - If no Location based Applications were found

     *                       with the required configuration.

     * @leave KErrNotSupported - If Location Centre cannot be launched. This

     *                           generally occurs when the Client application

     *                           does not have a UI context.

     * @leave KErrServerTerminated - If the Location Centre server terminates

     *                               prematurely. In this case, all future

     *                               requests to Location Centre would also

     *                               fail with the same error code.        

     * @leave System wide error code if the operation fails due to some other

     *        reason.

     */                        

    IMPORT_C void LaunchLocationCentreL(

        const RArray<TPtrC>&              aExcludeAppArray,

        CLcLocationAppInfo::TLcLaunchMode aLaunchMode = CLcLocationAppInfo::EDefaultMode,

        MLcAppExitObserver*               aChainedAppExitObserver = NULL );

    /**

     * Launches Location Centre as a pop-up dialog with a list of

     * Location based Applications and the user can select a Location

     * based Application from the pop-up list displayed.

     * 

     * @since S60 v5.0

     * @return If the terminal User has selected a Location based Application,

     *         Unique identifier identifying the Location based Application

     *         which was selected.

     *         NULL string incase the terminal User cancelled the pop-up dialog.

     *         The string returned is a reference to this object's internal string. Hence,

     *         the Client Application must copy the string if it expects to retain

     *         it.

     * @leave KErrInUse - If there is an outstanding request present on Location Centre.     

     * @leave KErrNotFound - If no Location based Applications were found.

     * @leave KErrNotSupported - If Location Centre cannot be launched. This

     *                           generally occurs when the Client application

     *                           does not have a UI context.

     * @leave KErrServerTerminated - If the Location Centre server terminates

     *                               prematurely. In this case, all future

     *                               requests to Location Centre would also

     *                               fail with the same error code.    

     * @leave System wide error code if the operation fails due to some other

     *        reason.

     */     

    IMPORT_C TPtrC SelectLocationApplicationL();

     /**

     * Launches Location Centre as a pop-up dialog with a filtered list of

     * Location based Applications and the user can select a Location

     * based Application from the pop-up list displayed.

     * 

     * The Client application can configure Location Centre to display 

     * only a subset of Location based Applications. This can be achieved

     * by passing an object of type @ref TLcLocationAppFilter as the

     * parameter to this function. Only those Location based Applications

     * which satisfy the filter conditions are displayed in Location Centre. 

     * The user can select any of the Location based Applications displayed

     * in the pop-up list and the identifier corresponding to the selected

     * Location based Application would be returned back to the user.

     *

     * The ownership of the filter is not transferred to Location Centre.   

     *     

     * @since S60 v5.0

     * @param[in] aLocationAppFilter Filter that needs to be applied 

     *                               to customize the list of Location

     *                               based Applications to be displayed in

     *                               Location Centre.     

     * @return If the terminal User has selected a Location based Application,

     *         Unique identifier identifying the Location based Application

     *         which was selected.

     *         NULL string incase the terminal User cancelled the pop-up dialog.

     *         The string returned is a reference to this object's internal string. Hence,

     *         the Client Application must copy the string if it expects to retain

     *         it.     

     * @leave KErrInUse - If there is an outstanding request present on Location Centre.     

     * @leave KErrNotFound - If no Location based Applications were found.

     * @leave KErrNotSupported - If Location Centre cannot be launched. This

     *                           generally occurs when the Client application

     *                           does not have a UI context.

     * @leave KErrServerTerminated - If the Location Centre server terminates

     *                               prematurely. In this case, all future requests

     *                               to Location Centre would also fail with

     *                               the same error code.    

     * @leave System wide error code if the operation fails due to some other

     *        reason.

     */     

    IMPORT_C TPtrC SelectLocationApplicationL( 

                const TLcLocationAppFilter&         aLocationAppFilter );

    /**

     * Launches Location Centre with based Applications in a pop-up

     * dialog and the user can select a Location based Application

     * from the pop-up list displayed.

     *

     * The Client application can configure Location Centre to either

     * display only those Location based Applications specified in

     * the array or to display all Location based Applications other

     * than those specified in the array.

     * The user can select any of the Location based Application displayed

     * in the pop-up list and the identifier corresponding to the selected

     * Location based Application would be returned back to the user.

     *

     * The ownership of the specified array is not tranferred to Location

     * Centre.

     *

     * @since S60 v5.0         

     * @param[in] aArray  Array of Location based Applications which

     *                    are to be displayed in Location Centre.

     * @param[in] aIncludeFlag If the flag value is

     *                         - ETrue, then only those Location based

     *                           Applications specified in the array would

     *                           be displayed in Location Centre.

     *                         - EFalse, then all Location based Applications

     *                           other than those specified in the array

     *                           would be displayed in Location Centre.

     * @return If the terminal User has selected a Location based Application,

     *         Unique identifier identifying the Location based Application

     *         which was selected.

     *         The string returned is a reference to this object's internal string. Hence,

     *         the Client Application must copy the string if it expects to retain

     *         it.     

     *         NULL string incase the terminal User cancelled the pop-up dialog.

     * @leave KErrInUse - If there is an outstanding request present on Location Centre.     

     * @leave KErrNotFound - If none of the specified Location based