diff -r 000000000000 -r 522cd55cc3d7 loc_plat/location_centre_api/inc/lcservice.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/loc_plat/location_centre_api/inc/lcservice.h Tue Feb 02 00:16:03 2010 +0200 @@ -0,0 +1,841 @@ +/* +* 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 + +// 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& 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& 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 + * 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 TPtrC SelectLocationApplicationL( + const RArray& aAppArray, + TBool aIncludeFlag ); + + /** + * Gets a list of all Location based Applications. + * + * This function returns a list of all Location based Applications + * to the caller. + * + * The ownership of the list of Location based Applications is + * transferred to the caller. + * + * @since S60 v5.0 + * @param[in] aLocationAppFilter Filter that needs to be applied + * to customize the list of Location + * Applications to be retrieved from + * Location Centre. + * @return CLcLocationAppInfoArray object containing a list + * of applications registered with Location Centre. + * @leave KErrNotFound, If there are no Location based Applications + * available. + * @leave KErrInUse - If there is an outstanding request present on Location Centre. + * @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 array retrieval fails for + * any other reason. + */ + IMPORT_C CLcLocationAppInfoArray* GetLocationApplicationsL(); + + /** + * Gets a list of all Location based Applications. + * + * This is an asynchronous version and at any instant of time there + * can be only one such request outstanding. + * + * The ownership of the list of Location based Applications is + * transferred to the caller. + * + * @since S60 v5.0 + * @param[out] aStatus Status variable on which the completion of the + * request would be communicated. The following + * are the values which the variable can assume + * on completion of the request. + * Since, the CLcService class will use its internal + * Active object for interacting with the Location + * Centre server and not this aStatus directly, the + * Client application must not use User::WaitforRequest + * on this status variable. + * - KErrNone, If the list of applications was + * successfully retrieved. + * - KErrInUse, If there is an outstanding + * request present on Location Centre. + * - KErrNotFound, If there are no Location + * based Applications available. + * - KErrCancel, If an outstanding request is + * Cancelled. + * - 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. + * - System wide error code if the array retrieval + * fails for any other reason. + * @param[out] aAppInfoArray Reference to the pointer of Application + * information array. This pointer would be + * updated with the @ref CLcLocationAppInfoArray + * object containing a list of applications + * registered with Location Centre on the + * asynchronous completion of this function. + */ + IMPORT_C void GetLocationApplications( + TRequestStatus& aStatus, + CLcLocationAppInfoArray*& aAppInfoArray ); + + /** + * Gets a filtered list of Location based Applications. + * + * The Client application can configure the list of Location based + * Applications returned. This can be achieved by passing an object + * of type @ref TLcLocationAppFilter as the parameter to this function. + * + * The ownership of the filter is not transferred to Location Centre. + * + * The ownership of the list of Location based Applications is + * transferred to the caller. + * + * @since S60 v5.0 + * @param[in] aLocationAppFilter Filter that needs to be applied + * to customize the list of Location + * Applications to be retrieved from + * Location Centre. + * @return CLcLocationAppInfoArray object containing a list + * of applications registered with Location Centre. + * @leave KErrNotFound If there are no Location based Applications + * corresponding to the filter paramter. + * @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 array retrieval fails for + * any other reason. + */ + IMPORT_C CLcLocationAppInfoArray* GetLocationApplicationsL( + const TLcLocationAppFilter& aLocationAppFilter ); + + /** + * Gets a filted list of Location based Applications. + * + * The Client application can configure the list of Location based + * Applications returned. This can be achieved by passing an object + * of type @ref TLcLocationAppFilter as the parameter to this function. + * This is an asynchronous version and at any instant of time there + * can be only one such request outstanding. + * + * The ownership of the filter is not transferred to Location Centre. + * + * The ownership of the list of Location based Applications is + * transferred to the caller. + * + * @since S60 v5.0 + * @param[out] aStatus Status variable on which the completion of the + * request would be communicated. The following + * are the values which the variable can assume + * on completion of the request. + * Since, the CLcService class will use its internal + * Active object for interacting with the Location + * Centre server and not this aStatus directly, the + * Client application must not use User::WaitforRequest + * on this status variable. + * - KErrNone, If the list of applications was + * successfully retrieved. + * - KErrInUse, If there is an outstanding + * request present. + * - KErrCancel, If an outstanding request is + * Cancelled. + * - 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. + * - System wide error code if the array retrieval + * fails for any other reason. + * @param[in] aLocationAppFilter Filter that needs to be applied + * to customize the list of Location + * Applications to be retrieved from + * Location Centre. + * @param[out] aAppInfoArray Reference to the pointer of Application + * information array. This pointer would be + * updated with the @ref CLcLocationAppInfoArray + * object containing a list of applications + * registered with Location Centre on the + * asynchronous completion of this function. + */ + IMPORT_C void GetLocationApplications( + TRequestStatus& aStatus, + const TLcLocationAppFilter& aLocationAppFilter, + CLcLocationAppInfoArray*& aAppInfoArray ); + + /** + * Cancels an outstanding @ref GetLocationApplications request. + */ + IMPORT_C void CancelGetLocationApplications(); + + /** + * Launches a Location based Application in the desired mode. + * + * The identifier passed to te function is first validated for + * existence and registration with Location Centre. Incase, the + * Location based Application exists and its has already registered with + * Location Centre, then the function launches the Location + * Application in the desired mode. + * + * @since S60 v5.0 + * @param[in] aAppIdentifier Unique identifier identifying the + * Location based Application. + * @param [in] aLaunchMode Mode in which the all 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 chained + * application termination. If a value + * is specified for the observer for + * Stand alone lauunching then the + * Observer value would be ignored. + * @leave KErrNotFound, If there is no Location based Application + * corresponding to the identifer or if the Location + * based Application cannot be launched in the + * specified mode. + * @leave KErrInUse - If there is an outstanding request present on Location + * Centre. + * @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 for any other + * reason. + */ + IMPORT_C void LaunchLocationApplicationL( + const TDesC& aAppIdentifier, + CLcLocationAppInfo::TLcLaunchMode aLaunchMode = CLcLocationAppInfo::EDefaultMode, + MLcAppExitObserver* aChainedAppExitObserver = NULL ); + + /** + * Sets an observer for notifying changes to the Location Centre server. + * + * The notification can occur under the following conditions + * - When a new Location based Application registers into Location Centre. + * In this case, the Location based Application would be immediately available + * for all Location Centre operations. + * - When an already registered Location based Application de-registers. + * In this case, the Location based Application will be removed from Location + * Centre. Hence, it would not be available for any further Location Centre + * operations. + * - When a Location based Application is present on a removable media + * (like Memory card) and the media is removed. In this case, for all practical + * purposes the Location based Application behaves as in the previous context. + * The difference being that the Location based Application does not get removed + * from Location Centre but is marked as an Absent application. When the + * removable media is re-inserted, the Location based Application immediately + * becomes available for all Location Centre operations. + * - When an removable media containing an Absent Application is re-inserted. In + * this case, the Location based Application would be immediately available for + * all Location Centre operations. + * - When the Location Centre server terminates pre-maturely. In this case, no + * further notifications would be given to the Client application and all + * further requests to the Location Centre server would fail with + * @p KErrServerTerminated. + * + * @since S60 v5.0 + * @param[in] aObserver Observer to which notification would be issued. + * @leave KErrAlreadyExists If the observer has already been set. + * @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. + */ + IMPORT_C void SetObserverL( MLcNotification& aObserver ); + + /** + * Removes the observer that has already been set using the @ref SetObserverL method. + * + * @since S60 v5.0 + * @return KErrNone, If the observer removal was successful. + * KErrNotFound, If no observer was set previously. + */ + IMPORT_C TInt RemoveObserver(); + +private: + /** + * Default C++ Constructor. + */ + CLcService(); + + /** + * Overloaded Copy Constructor. By default, prohibit copy constructor + * + * @param[in] aLocationCentre Location Centre interface object from which the new + * object should be constructed. + */ + CLcService( const CLcService& aLocationCentre ); + + /** + * Overloaded Assignment operator. By default, prohibit assignment + * operator + * + * @param[in] aLocationCentre Location Centre interface object from which the new + * object should be assigned. + * @return the Location Centre interface object after assigment. + */ + CLcService& operator= ( + const CLcService& aLCAppInfo ); + + /** + * Second phase of the two phase constructor. + */ + void ConstructL(); + +private: // Data + /** + * Location Centre Implementation. Hides the actual implementation + * of the Location Centre API. + * + * Owns + */ + CLcServiceImpl* iImplementation; + }; + +#endif // C_LCSERVICE_H