williamr@4: /*
williamr@4: * Copyright (c) 2009 NTT DOCOMO, INC. All Rights Reserved.
williamr@4: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@4: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@4: *
williamr@4: * Initial Contributors:
williamr@4: * NTT DOCOMO, INC. - initial contribution.
williamr@4: * Nokia Corporation - additional changes.
williamr@4: * 
williamr@4: * Contributors:
williamr@4: * 
williamr@4: * Description:
williamr@4: *
williamr@4: */
williamr@4: 
williamr@4: /**
williamr@4:  @file
williamr@4:  @publishedPartner
williamr@4:  @released
williamr@4: */
williamr@4: 
williamr@4: #ifndef LBS_PRIVACY_CONTROLLER_H
williamr@4: #define LBS_PRIVACY_CONTROLLER_H
williamr@4: 
williamr@4: #include <e32std.h>
williamr@4: 
williamr@4: class TLbsExternalRequestInfo;
williamr@4: class TPositionInfo;
williamr@4: class CLbsPrivacyControllerImpl;
williamr@4: 
williamr@4: 
williamr@4: /**
williamr@4: The mixin class that defines the interface for the LBS privacy 
williamr@4: controller observer.
williamr@4: 
williamr@4: @publishedPartner
williamr@4: @released 
williamr@4: 
williamr@4: The callbacks defined in this class are called by the LBS system 
williamr@4: when needed, e.g. when a network location request is received, 
williamr@4: when the reference position is received, when the final position 
williamr@4: is calculated and when the request has completed.
williamr@4: */
williamr@4: class MLbsPrivacyObserver
williamr@4: 	{
williamr@4: public:
williamr@4: 	/** Contains the user notification action defined by the 
williamr@4: 	network location request (MT-LR). This setting may be
williamr@4: 	overridden by the setting(s) in the LBS Admin Settings API.
williamr@4: 	
williamr@4: 	@see CLbsAdmin::TExternalLocateService
williamr@4: 	@see CLbsAdmin::TPrivacyTimeoutAction
williamr@4: 	*/
williamr@4: 	enum TNotificationType
williamr@4: 		{
williamr@4: 		/** Unused/Unknown notification. */
williamr@4: 		ENotifyUnknown = 0,
williamr@4: 		/** Accept and notify user.*/
williamr@4: 		ENotifyLocationAccepted,
williamr@4: 		/** Verify (query user). Accept if no response.*/
williamr@4: 		ENotifyAndVerifyLocationAcceptedIfNoReponse,
williamr@4: 		/** Verify (query user). Reject if no response.*/
williamr@4: 		ENotifyAndVerifyLocationRejectedIfNoReponse,
williamr@4: 		/** Reject and notify user.*/
williamr@4: 		ENotifyLocationRejected,
williamr@4: 		};
williamr@4: 
williamr@4: public:
williamr@4: 	IMPORT_C virtual TVersion Version();
williamr@4: 	
williamr@4: 	/**
williamr@4: 	Called when a network location request is received by the LBS system.
williamr@4: 	The implementer of this function must decide whether the location request 
williamr@4: 	is allowed and give the result to the LBS system. The result is passed 
williamr@4: 	by calling CPrivacyController::SendRequestVerificationResult().
williamr@4: 	
williamr@4: 	@param aRequestId Identifies the request within the LBS system.
williamr@4: 	@param aRequestInfo Information about the external client making the request.
williamr@4: 	  Note that the actual type may be of one the derived classes
williamr@4: 	  e.g. TLbsExternalRequestInfo2.
williamr@4: 	  The type may be determined by calling ClassType().
williamr@4: 	  If the class is of the TLbsExternalRequestInfo2 type, this parameter may be 
williamr@4: 	  casted to access the extended information.
williamr@4: 	@param aNotificationType The value set by the network for the user notification.
williamr@4: 	
williamr@4: 	@see TLbsExternalRequestInfo2
williamr@4: 	@see TLbsLocClassTypeBase::ClassType()
williamr@4: 	*/
williamr@4: 	virtual void ProcessNetworkLocationRequest(TUint aRequestId, const TLbsExternalRequestInfo& aRequestInfo, const TNotificationType& aNotificationType) = 0;
williamr@4: 	
williamr@4: 	/**
williamr@4: 	Called whenever a position update is ready while processing a network 
williamr@4: 	location request. Typically, it will be called twice:
williamr@4: 	1) As soon as the network reference position is available.
williamr@4: 	2) As soon as the final calculated position is available.
williamr@4: 	
williamr@4: 	@param aRequestId Identifies the request within the LBS system.
williamr@4: 	@param aPosInfo The latest position data.
williamr@4: 	*/
williamr@4: 	virtual void ProcessNetworkPositionUpdate(TUint aRequestId, const TPositionInfo& aPosInfo) = 0;
williamr@4: 	
williamr@4: 	/**
williamr@4: 	Called when a network location request (e.g. MT-LR) has been completed.
williamr@4: 	
williamr@4: 	@param aRequestId Identifies the request within the LBS system.
williamr@4: 	@param aReason Contains the reason for the completion of the request.
williamr@4: 	               Usually KErrNone, or a standard Symbian error code.
williamr@4: 	               KErrNotFound if aRequestId is not a currently 
williamr@4: 	               active external location request.
williamr@4: 	*/
williamr@4: 	virtual void ProcessRequestComplete(TUint aRequestId, TInt aReason) = 0;
williamr@4: 	};
williamr@4: 
williamr@4: 
williamr@4: /**
williamr@4: The mixin class that defines an extended interface for the LBS privacy 
williamr@4: controller observer.
williamr@4: 
williamr@4: It should be used only if the start up of a Privacy Controller process 
williamr@4: (platform specific, not a part of LBS) is controlled by the LBS sub-system
williamr@4: by adding the name of the Privacy Controller process to the LBS Root Process
williamr@4: configuration file.
williamr@4: 
williamr@4: @see MLbsPrivacyObserver
williamr@4: @see CLbsPrivacyController
williamr@4: 
williamr@4: @publishedPartner
williamr@4: @released
williamr@4: */
williamr@4: class MLbsPrivacyObserver2 : public MLbsPrivacyObserver
williamr@4: 	{
williamr@4: public:
williamr@4: 	IMPORT_C virtual TVersion Version();
williamr@4: 	
williamr@4: 	/**
williamr@4: 	Called whenever the LBS sub-system is closing down.
williamr@4: 	After receiving the call the current process MUST close itself down.
williamr@4: 	
williamr@4: 	@param aReservedParam Reserved for future extensions.
williamr@4: 	*/
williamr@4: 	virtual void ProcessCloseDownNotification(TInt32 aReservedParam) = 0;
williamr@4: 	};
williamr@4: 
williamr@4: 
williamr@4: /**
williamr@4: An application can use this class to register itself as the user
williamr@4: privacy controller for the LBS system. 
williamr@4: 
williamr@4: The application must supply an implementation of the MLbsPrivacyObserver 
williamr@4: interface so that it can be notified of important events. 
williamr@4: 
williamr@4: When it receives the MLbsPrivacyObserver::ProcessNetworkLocationRequest()
williamr@4: notification it must reply by calling 
williamr@4: CLbsPrivacyController::RespondNetworkLocationRequest() to tell the 
williamr@4: LBS system the user response to the network location request.
williamr@4: 
williamr@4: If the request was accepted then the application will recieve more 
williamr@4: notifications:
williamr@4: 1) MLbsPrivacyObserver::ProcessNetworkPositionUpdate() with the reference
williamr@4: position when the assistance data is received from the network.
williamr@4: 2) MLbsPrivacyObserver::ProcessNetworkPositionUpdate() with the calculated
williamr@4: position when it is sent back to the network.
williamr@4: 3) MLbsPrivacyObserver::ProcessRequestCompleted() when the application
williamr@4: no longer needs to listen to notifications for that request.
williamr@4: 
williamr@4: Each notification contains aRequestId, which identifies each network
williamr@4: location request within the LBS system. It is meant to be used so that
williamr@4: each of the different notifications can be matched to the request they
williamr@4: came from.
williamr@4: */	
williamr@4: NONSHARABLE_CLASS(CLbsPrivacyController) : public CBase
williamr@4: 	{
williamr@4:   public:
williamr@4:   	/** The user response to the network location request dialog. */
williamr@4:   	enum TRequestVerificationResult
williamr@4:   		{
williamr@4:   		/** Unused request. */
williamr@4:   		ERequestUnknown = 0,
williamr@4:   		/** Request accepted (permission granted). */
williamr@4:   	   	ERequestAccepted,
williamr@4:   		/** Request rejected (permission denied). */
williamr@4:   	   	ERequestRejected,
williamr@4:   		/** Tell the Lbs system to ignore the request. Currently not implemented. */
williamr@4:   		ERequestIgnore
williamr@4:   		};
williamr@4: 		
williamr@4: public:
williamr@4: 	IMPORT_C static CLbsPrivacyController* NewL(MLbsPrivacyObserver& aObserver);
williamr@4: 	~CLbsPrivacyController();
williamr@4: 	
williamr@4: 	IMPORT_C void RespondNetworkLocationRequest(TUint aRequestId, TRequestVerificationResult aResult);
williamr@4: 	
williamr@4: 	IMPORT_C void CancelNetworkLocationRequest(TUint aRequestId);
williamr@4: 
williamr@4: private:
williamr@4: 	CLbsPrivacyController();
williamr@4: 	void ConstructL(MLbsPrivacyObserver& aObserver);
williamr@4: 	
williamr@4: private:
williamr@4: 	/** CLbsPrivacyControllerImp* Impl is the internal handle to the Implementation */
williamr@4: 	CLbsPrivacyControllerImpl* iImpl;
williamr@4: 	};
williamr@4: 
williamr@4: 	
williamr@4: #endif // LBS_PRIVACY_CONTROLLER_H