sl@0: /*
sl@0: * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: * All rights reserved.
sl@0: * This component and the accompanying materials are made available
sl@0: * under the terms of the License "Eclipse Public License v1.0"
sl@0: * which accompanies this distribution, and is available
sl@0: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: *
sl@0: * Initial Contributors:
sl@0: * Nokia Corporation - initial contribution.
sl@0: *
sl@0: * Contributors:
sl@0: *
sl@0: * Description: 
sl@0: * Interface definition for UPS dialog creator ECOM plug-in.
sl@0: *
sl@0: */
sl@0: 
sl@0: 
sl@0: /**
sl@0:  @file
sl@0:  @publishedPartner
sl@0:  @released
sl@0: */
sl@0: 
sl@0: #ifndef DIALOGCREATOR_H
sl@0: #define DIALOGCREATOR_H
sl@0: 
sl@0: #include <e32base.h>
sl@0: #include <e32cmn.h>
sl@0: #include <ups/policy.h>
sl@0: #include <ups/ups.hrh>
sl@0: 
sl@0: namespace UserPromptService
sl@0: 	{
sl@0: 	class CClientEntity;
sl@0: 	class CFingerprint;
sl@0: 	class CPromptRequest;
sl@0: 	
sl@0: 	/**
sl@0: 	Abstract base class for dialog creator ECOM plug-ins.
sl@0: 	
sl@0: 	Dialog creators are responsible for generating and displaying prompt dialogs. Normally,
sl@0: 	the notifier framework (RNotifier) would be used to interact with the user interface layer.\n
sl@0: 	
sl@0: 	In addition to the data supplied by the system server the dialog creator may
sl@0: 	also include data from other servers such as AppArc or the SIS registry.
sl@0: 	Since retrieving this extra information may take an unpredictable amount of time the dialog
sl@0: 	creator PrepareDialog method is asynchronous to ensure the user prompt service is 
sl@0: 	not blocked.
sl@0: 
sl@0: 	- A new dialog creator object is created for each request that requires a prompt. The object
sl@0: 	is destroyed after DisplayDialog has been called.
sl@0: 	*/			
sl@0: 	class CDialogCreator : public CActive
sl@0: 		{
sl@0: 	public:					
sl@0: 		IMPORT_C static CDialogCreator* NewL(const TUid& aDialogCreatorImplementationId);
sl@0: 		
sl@0: 		/**
sl@0: 		 Asynchronously retrieves and prepares the data needed to display the dialog.
sl@0: 		 
sl@0: 		 The const parameters aRequest, aPolicy, aFingerprints, aDialogCreatorParams persist
sl@0: 		 until after the the dialog creator has been destroyed; therefore, the dialog creator
sl@0: 		 may safely use pointers to this data internally.\n
sl@0: 		 
sl@0: 		 @param aRequest				The parameters supplied by the system server.
sl@0: 		 @param aPolicy					The policy being evaluated.
sl@0: 		 @param aFingerprints			The array of finger prints generated by the policy evaluator.\n
sl@0: 										This may be empty if the policy does not allow the Always or Never options.
sl@0: 		 @param aClientEntity			Identifies the entity within the client process that requested the service.\n
sl@0: 										NULL if the client processs is not an execution host.
sl@0: 		 @param	aDialogCreatorParams	Opaque data generated by the policy evaluator.
sl@0: 		 @param aStatus					The request object to complete once the dialog is ready.
sl@0: 		*/
sl@0: 		virtual void PrepareDialog(
sl@0: 			const CPromptRequest& aRequest, 
sl@0: 			const CPolicy& aPolicy,			
sl@0: 			const RPointerArray<CFingerprint>& aFingerprints,
sl@0: 			const CClientEntity* aClientEntity,
sl@0: 			const TAny* aDialogCreatorParams,
sl@0: 			TRequestStatus& aStatus) = 0;
sl@0: 
sl@0: 		/**
sl@0: 		Asynchronously, displays the dialog created by PrepareDialog and interprets the result.	
sl@0: 
sl@0: 		Note that the UPS server expects aOptionSelected to match one of the enabled options specified 
sl@0: 		in the policy entry which was passed into PrepareDialog. If no legal option is selected, it will be treated
sl@0: 		as a ENo.
sl@0: 
sl@0: 		@param aOptionSelected	The option selected by the user.\n
sl@0: 								(OUT parameter)
sl@0: 		@param aFingerprint		A reference to a pointer used to return	the fingerprint to use in the new
sl@0: 								decision record if the Always or Never button was selected.\n
sl@0: 								Ownership is NOT transferred to the caller.\n
sl@0: 								(OUT parameter)
sl@0: 		@param aEvaluatorInfo	The value to write to the decision record's evaluatorInfo field if
sl@0: 								the Always or Never option was selected. The default 
sl@0: 								value for this field is 0x00000000 for a new record or the
sl@0: 								previous value if the policy evaluator forced a prompt to be
sl@0: 								displayed and a decision record already existed.\n
sl@0: 								(IN/OUT parameter)
sl@0: 		@param aStatus			The request object to complete once the dialog has been closed.
sl@0: 								
sl@0: 		 */
sl@0: 		virtual void DisplayDialog(
sl@0: 			CPolicy::TOptions& aOptionSelected,
sl@0: 			const CFingerprint*& aFingerprint,
sl@0: 			TUint& aEvaluatorInfo,
sl@0: 			TRequestStatus& aStatus) = 0;
sl@0: 					
sl@0: 		IMPORT_C TInt GetExtension(TUint aExtensionId, TAny*& a0, TAny* a1);		
sl@0: 		IMPORT_C ~CDialogCreator();		
sl@0: 	protected:
sl@0: 		IMPORT_C CDialogCreator();
sl@0: 		IMPORT_C virtual TInt Extension_(TUint aExtensionId, TAny*& a0, TAny* a1);
sl@0: 	private:
sl@0: 		TAny* iReserved;
sl@0: 		TUid iDtor_ID_Key;		// Required by ECOM
sl@0: 		};		
sl@0: 	}	
sl@0: 
sl@0: #endif // DIALGOCREATOR_H