/*

 * Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of the License "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: 

 *

 */

 /**

  @file

  @publishedPartner

  @released

 */

 #ifndef __SECDLG_H__

 #define __SECDLG_H__

 #include <ct.h>

 #include <securitydefs.h>

 /** Security Dialog API */

 /** The maximum length of a PIN label */

 const TInt KPINLabelMaxLength = 64;

 /** TPINLabel is a human-readable name for the PIN to be entered. */

 //64 = 255 bytes / poss 4bytes per unicode character

 typedef TBuf<KPINLabelMaxLength> TPINLabel;

 /**

  * Provides information associated with the PIN, 

  * to enable the dialog to display the name and do some basic correctness checking.

  */

 class TPINParams

 	{

 public:

 	/** The label that identifies the PIN */

 	TPINLabel iPINLabel;

 	/** The label of the token */

 	TPINLabel iTokenLabel;

 	/** The minimum length of the PIN */

 	TInt iMinLength;

 	/** The maximum length of the PIN */

 	TInt iMaxLength;

 	};

 /** The max PIN length should not exceed 32, because this is the maximum

  *	size possible in the CEikSecretEditor class. */

 const TInt KMaxPINLength = 32;

 /** A PIN value */

 typedef TBuf<KMaxPINLength> TPINValue;

 /** Unblocking PINs can be up to 64 characters if they are entered in the clear. */

 const TInt KMaxUnblockPINLength = 64;

 /** An unblocking PIN value */

 typedef TBuf<KMaxUnblockPINLength> TUnblockPINValue;

 /**

  * Definition of the security dialog interface

  * @since 7.0

  */

 class MSecurityDialog 

 	{

 public:

 	/**

 	 * TConnectionType defines the possible protocols used in EstablishSecureConnection

 	 * which allows the type of the certificate to be derived.

 	 */

 	enum TConnectionType

 		{

 		/** WTLS */

 		EWTLS,

 		/** TLS */

 		ETLS

 		};

 public:

 	/**

 	 * Prompts the user to enter a PIN. 

 	 *

 	 * @param aPINParams	Information about the PIN to enter.

 	 * @param aRetry		Indicates whether the user is retrying.

 	 * @param aPINValue		On return, the PIN the user entered: 

 	 * @param aStatus		This will be set to KErrNotFound if no certificates could

 	 * 						be presented to the user.

 	 */

 	virtual void EnterPIN( const TPINParams& aPINParams, TBool aRetry, TPINValue& aPINValue,

 						   TRequestStatus& aStatus ) = 0;

 	/**

 	 * Prompts the user to change a PIN. 

 	 * 

 	 * @param aPINParams	Information about the PIN to change

 	 * @param aRetry		Indicates whether the user is retrying

 	 * @param aOldPINValue	On return, the old PIN the user entered 

 	 * @param aNewPINValue	On return, the new PIN the user entered

 	 * @param aStatus		This will be set to KErrNotFound if no certificates could

 	 * 						be presented to the user.

 	 */

 	virtual void ChangePIN( const TPINParams& aPINParams, TBool aRetry,

 							TPINValue& aOldPINValue, TPINValue& aNewPINValue,

 							TRequestStatus& aStatus ) = 0;

 	/**

 	 * Prompts the user to enable a PIN. 

 	 * 

 	 * @param aPINParams	Information about the PIN to enable.

 	 * @param aRetry		Indicates whether the user is retrying.

 	 * @param aPINValue		On return, the PIN the user entered: 

 	 * @param aStatus		This will be set to KErrNotFound if no certificates could

 	 * 						be presented to the user.

 	 */

 	virtual void EnablePIN( const TPINParams& aPINParams, TBool aRetry, TPINValue& aPINValue,

 							TRequestStatus& aStatus ) = 0;

 	/**

 	 * Prompts the user to disable a PIN. 

 	 * 

 	 * @param aPINParams	Information about the PIN to disable.

 	 * @param aRetry		Indicates whether the user is retrying. 

 	 * @param aPINValue		On return, the PIN the user entered: 

 	 * @param aStatus		This will be set to KErrNotFound if no certificates could

 	 * 						be presented to the user.

 	 */

 	virtual void DisablePIN( const TPINParams& aPINParams, TBool aRetry,

 								TPINValue& aPINValue, TRequestStatus& aStatus ) = 0;

 	/**

 	 * Prompts the user to unblock a PIN. 

 	 *

 	 * The unblocking PIN is not displayed as it is entered, and can be a

 	 * maximum of 32 characters long - hence it is passed back as a TPINValue.

 	 * 

 	 * @param aBlockedPINParams		Information about the PIN to unblock

 	 * @param aUnblockingPINParams	Information about the unblocking PIN

 	 * @param aRetry				Indicates whether the user is retrying

 	 * @param aUnblockingPINValue	On return, the PIN the user entered

 	 * @param aNewPINValue			On return, the new PIN the user entered

 	 * @param aStatus				This will be set to KErrNotFound if no certificates could

 	 * 								be presented to the user.

 	 */	

 	virtual void UnblockPIN( const TPINParams& aBlockedPINParams,

 							 const TPINParams& aUnblockingPINParams, TBool aRetry,

 							 TPINValue& aUnblockingPINValue, TPINValue& aNewPINValue,

 							 TRequestStatus& aStatus ) = 0;

 	/**

 	 * Informs the user that the PIN has become blocked.

 	 * 

 	 * @param aPINParams	Information about the blocked PIN.

 	 * @param aStatus		This will be set to KErrNotFound if no certificates could

 	 * 						be presented to the user.

 	 */

 	virtual void PINBlocked( const TPINParams& aPINParams, TRequestStatus& aStatus ) = 0;

 	/**

 	 * Informs the user that a secure connection is being established with the given

 	 * server, allowing them to proceed or cancel the operation.

 	 * 

 	 * @param aCertData					The certificate sent by the server.

 	 * @param aCertHandleList			A selection of certificates to display to the user. All

 	 *									certificates are displayed if this is empty.

 	 * @param aConnectionType			This allows the type of certificate to be identified.

 	 * @param aDoClientAuthentication	Determines whether the user is prompted to

 	 * 									agree to authenticate themselves to the server.

 	 * 									If this was true before the function was called, it

 	 * 									will contain the result of the user's decision on return.

 	 * @param aCertHandle				An identifier for the certificate the user selected.

 	 * @param aStatus					This will be set to KErrNotFound if no certificates could

 	 * 									be presented to the user.

 	 */	

 	virtual void EstablishSecureConnection( const TDesC8& aCertData,

 						const RArray<TCTTokenObjectHandle>& aCertHandleList,

 						MSecurityDialog::TConnectionType aConnectionType,

 						TBool& aDoClientAuthentication, TCTTokenObjectHandle& aCertHandle,

 						TRequestStatus& aStatus ) = 0;

 	/**

 	 * Signs some text.

 	 * 

 	 * @param aTextToSign		The text to be signed.

 	 * @param aCertHandleList	A selection of certificates to display to the user.

 	 *							All certificates are displayed if this is empty.

 	 * @param aCertHandle		On return, an identifier for the certificate the user selected.

 	 * 							aStatus - this will be set to KErrNotFound if no certificates

 	 *							could be presented to the user.

 	 * @param aStatus			This will be set to KErrNotFound if no certificates could

 	 * 							be presented to the user.

 	 */

 	virtual void SignText( const TDesC& aTextToSign,

 							const RArray<TCTTokenObjectHandle>& aCertHandleList, 

 							TCTTokenObjectHandle& aCertHandle,

 							TRequestStatus& aStatus ) = 0;

 	/**

 	 * Frees resources of the MSecurityDialog class

 	 */

 	virtual void Release()=0;

 	/**

 	 * Informs the user that the server authentication has failed.

 	 *

 	 * @param aServerName	 The name of the server.

 	 * @param aFailurereason The server authentication failure reason

 	 * @param aencodedCert	 The certificate sent by the server.

 	 * @param aStatus		 This will be set to KErrNone or KErrAbort depending upon

 	 *						 the EContinue or EStop.

 	 *						 

 	 */

 	virtual void ServerAuthenticationFailure(const TDesC8& aServerName,

 						const TValidationError& aFailureReason, const TDesC8& aEncodedCert,

 						TRequestStatus& aStatus ) = 0;

 protected:

 	/**

 	 * Destructor for the MSecurityDialog class

 	 */

 	inline virtual ~MSecurityDialog()=0;

  public:

 	// This is at the end to preserve BC

 	/**

 	 * Informs the user that the unblock PIN has been blocked.

 	 * 

 	 * @param aPINParams	Information about the blocked PIN.

 	 * @param aStatus		This will be set to KErrNotFound if no certificates could

 	 * 						be presented to the user.

 	 */

 	virtual void TotalBlocked( const TPINParams& aPINParams, TRequestStatus& aStatus ) = 0;

 	/**

 	 * Prompts the user to unblock a PIN.

 	 *

 	 * The unblocking PIN is displayed to the user in the clear as it is

 	 * entered, and can be a maximum of 64 characters long - it is passed back

 	 * as a TUnblockPINValue.

 	 * 

 	 * @param aBlockedPINParams		Information about the PIN to unblock

 	 * @param aUnblockingPINParams	Information about the unblocking PIN

 	 * @param aRetry				Indicates whether the user is retrying

 	 * @param aUnblockingPINValue	On return, the PIN the user entered

 	 * @param aNewPINValue			On return, the new PIN the user entered

 	 * @param aStatus				This will be set to KErrNotFound if no certificates could

 	 * 								be presented to the user.

 	 */

 	virtual void UnblockPINInClear( const TPINParams& aBlockedPINParams,

 									const TPINParams& aUnblockingPINParams, TBool aRetry,

 									TUnblockPINValue& aUnblockingPINValue, TPINValue& aNewPINValue,

 									TRequestStatus& aStatus ) = 0;

 	/**

 	 * Cancels an ongoing dialog.

 	 */

 	virtual void Cancel() = 0; 

 	};

 inline MSecurityDialog::~MSecurityDialog() {}

 /**

  * Factory for creating the relevant concrete subclass of the security dialog

  */

 class SecurityDialogFactory

 	{

 public:

 	/**

 	 * Creates an instance of a subclass of MSecurityDialog. Implement to create

 	 * the appropriate security dialog

 	 * 

 	 * @return	An object that implements MSecurityDialog functions

 	 */

 	IMPORT_C static MSecurityDialog* CreateL();

 	};

 #endif