/*

 * Copyright (c) 2001-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 __MCTAOSTORE_H__

 #define __MCTAOSTORE_H__

 #include <ct.h>

 /** The UID for the authentication object interface. */

 const TInt KCTInterfaceAuthenticationObject = 0x101F51AE;

 /**

  * A timeout value for an auth object indicating that it stays open until

  * explicity closed.

  */

 const TInt KTimeoutNever = -1;

 /**

  * A timeout value for an auth object indicating that the authentication data

  * must be entered every time the protected objects are used.

  */

 const TInt KTimeoutImmediate = 0;

 /**

  * The status of an authentication object.

  */

 enum TCTAuthenticationStatus

 	{

 	/** The authentication object is enabled. If it is not enabled, the objects protected 

 	* by this authentication object can be accessed without authentication. */

 	EEnabled		= 0x80,

 	/** The reference data cannot be changed. */

 	EChangeDisabled	= 0x40,

 	/** The authentication cannot be unblocked. */

 	EUnblockDisabled	= 0x20,

 	/** The authentication object can be disabled. */

 	EDisableAllowed	= 0x10,

 	/** The authentication object is blocked, meaning that the

 	* unblocking PIN must be entered to re-enable the authentication object. */

 	EAuthObjectBlocked= 0x08,

 	};	

 /** 

  * This class allows authentication objects to be queried and manipulated.

  * 

  * Authentication objects are obtained from the MCTAuthenticationObjectList class, 

  * which is the class returned as the token interface. 

  */

 class MCTAuthenticationObject: public MCTTokenObject

 	{

 public:

 	/** Constructor */

 	inline MCTAuthenticationObject(MCTToken& aToken);

 	// Listing Protected Objects

 	/** 

 	 * Gets a list of all the objects that this authentication object protects.

 	 * 

 	 * @param aObjects	The returned objects will be appended to this array.

 	 * @param aStatus	Completed with the return code when the operation completes. 

 	 */

 	virtual void ListProtectedObjects(RMPointerArray<MCTTokenObject>& aObjects, TRequestStatus& aStatus) = 0;

 	/** Cancels an asynchronous ListProtectedObjects() operation. */

 	virtual void CancelListProtectedObjects() = 0;

 	// Changing the reference data

 	/** 

 	 * Changes the reference data (e.g. PIN value).

 	 * 

 	 * The security dialog component will prompt for the old and new reference data.

 	 *

 	 * The authentication object may not allow its reference data to be changed -

 	 * this is indicated by the EChangeDisabled bit of Status() being set.

 	 * 

 	 * @param aStatus	Completed with the return code when the operation completes.

 	 *

 	 * @leave KErrNotFound If no reference data was originally set.

 	 */

 	virtual void ChangeReferenceData(TRequestStatus &aStatus) = 0;

 	/** Cancels an asynchronous ChangeReferenceData() operation. */

 	virtual void CancelChangeReferenceData() = 0;

 	/** 

 	 * Unblocks the authentication object.

 	 * 

 	 * The security dialog component will prompt for the unblocking

 	 * authentication object.

 	 *

 	 * It is only valid to call this method when the authentication object is

 	 * blocked, ie when the EAuthObjectBlocked bit of Status() is set.

 	 * 

 	 * The object may not allow unblocking (either because of failed unblock

 	 * attempts or because it doesn't support the concept) - this is indicated by

 	 * the EUnblockDisabled bit of Status() being set.

 	 * 

 	 * @param aStatus	Completed with the return code when the operation completes. 

 	 */

 	virtual void Unblock(TRequestStatus &aStatus) = 0;

 	/** Cancels an asynchronous Unblock() operation. */

 	virtual void CancelUnblock() = 0;

 	/** 

 	 * Gets the status of the authentication object.

 	 * 

 	 * @return	See TCTAuthenticationStatus() for the format of the return value. 

 	 */

 	virtual TUint32 Status() const = 0;

 	// Enabling and Disabling

 	/** 

 	 * Disables the authentication object.

 	 *

 	 *  It is only valid to call this method if the object is enabled, indicated

 	 *  by the EEnabled bit of Status() being set.

 	 *

 	 *  Also, the authentication object may not support being enabled/disabled -

 	 *  the EDisableAllowed bit of Status() must be set for this to work.

 	 *  

 	 * @param aStatus	Completed with the return code when the operation completes. 

 	 */

 	virtual void Disable(TRequestStatus &aStatus) = 0;

 	/** Cancels an asynchronous Disable() operation. */

 	virtual void CancelDisable() = 0;

 	/** 

 	 * Enables the authentication object.

 	 *

 	 *  It is only valid to call this method if the object is disabled, indicated

 	 *  by the EEnabled bit of Status() being clear.

 	 *

 	 *  Also, the authentication object may not support being enabled/disabled -

 	 *  the EDisableAllowed bit of Status() must be set for this to work.

 	 *  

 	 * @param aStatus	Completed with the return code when the operation completes. 

 	 */

 	virtual void Enable(TRequestStatus &aStatus) = 0;

 	// Cancel an ongoing Enable operation

 	/** Cancels an asynchronous Enable() operation. */

 	virtual void CancelEnable() = 0;

 	/** 

 	 * Opens the authentication object.

 	 * 

 	 * This means that the protected objects can be accessed without provoking

 	 * the authentication mechanism for the duration of the timeout period.

 	 * 	

 	 * Note that it is not strictly necessary to call this function, as the

 	 * authentication object will be opened when any operation that needs it to

 	 * be opened is called, but it is sometimes useful to control the timing of

 	 * authentication dialogs. Note also that this function will do nothing if

 	 * the authentication object is open, or if the authentication object

 	 * requires the authentication data to be entered every time.

 	 * 

 	 * @param aStatus	Completed with the return code when the operation completes.

 	 */

 	virtual void Open(TRequestStatus& aStatus) = 0;

 	/** 

 	 * Closes an authentication object. 

 	 * 

 	 * @param aStatus	Completed with the return code when the operation completes.

 	 */

 	virtual void Close(TRequestStatus& aStatus) = 0;

 	/** 

 	 * Gets the amount of time in seconds that the authentication object

 	 * will remain open for, or 0 if it is closed.

 	 * 

 	 * @param aStime		Time in seconds when the operation completes.

 	 * @param aStatus	Completed with the return code when the operation completes.

 	 */

 	virtual void TimeRemaining(TInt& aStime, TRequestStatus& aStatus) = 0;

 	/** 

 	 * Sets the time in seconds for this authentication object. 

 	 * 

 	 * Permitted values include 0, meaning always ask, and -1,

 	 * meaning until it's explicitly closed. Particular authentication

 	 * objects might restrict the range of values permitted.

 	 * 

 	 * @param aTime		Time in seconds

 	 * @param aStatus	Completed with the return code when the operation completes

 	 *

 	 * @leave KErrArgument If the timeout specified is invalid.

 	 */

 	virtual void SetTimeout(TInt aTime, TRequestStatus& aStatus) = 0;

 	/** 

 	 * Gets the current timeout value, in seconds. 

 	 * 

 	 * For an explanation of the values, see SetTimeout().

 	 * 

 	 * @param aTime		Time in seconds.

 	 * @param aStatus	Completed with the return code when the operation completes.

 	 */

 	virtual void Timeout(TInt& aTime, TRequestStatus& aStatus) = 0;

 	/** Cancels an asynchronous Open() operation. */

 	virtual void CancelOpen() {};

 	/** Cancels an asynchronous Close() operation. */

   	virtual void CancelClose() {};

 	/** Cancels an asynchronous TimeRemaining() operation. */

 	virtual void CancelTimeRemaining() {};

 	/** Cancels an asynchronous SetTimeout() operation. */

 	virtual void CancelSetTimeout() {};

 	/** Cancels an asynchronous Timeout() operation. */

 	virtual void CancelTimeout() {};

 	};

 /** 

  * An interface that enables clients to list all the authentication objects on 

  * a token, find out which objects they protect, and change/unblock/enable/disable them.

  * 

  * It may be used to implement a 'PIN manager' control panel item. This could 

  * list the PINs (by label), allow one to be selected, list what it is used for 

  * (including information such as what operations on that object are protected 

  * by that PIN), and then allow the user to change, enable, disable, and unblock 

  * the PIN.

  * 

  * Note that no PINs appear anywhere in this API. The code implementing this 

  * API will display a PIN dialog via the secure dialog interface when a PIN is 

  * required. The main advantage of this is that if some hostile code were to 

  * capture a PIN, it couldn't do anything with it as none of the APIs take a 

  * PIN. A secondary benefit is that the same API can work with biometrics or 

  * other methods of authentication. 

  */

 class MAuthenticationObjectList

 	{

 public:	

 	/** 

 	 * Gets a list of all the authenticaiton objects in the token.

 	 * 

 	 * This is an asynchronous request.

 	 * 

 	 * @param aAuthObjects	On return, a list of all the authentication objects.

 	 * @param aStatus		The request status object; contains the result of the List() request 

 	 * 						when complete. Set to KErrCancel if an outstanding request is cancelled. 

 	 */

 	// @param aAuthObjects	The returned authentication objects will be appended to this array

 	// @param aStatus		This will be completed with the final status code

 	virtual void List(RMPointerArray<MCTAuthenticationObject>& aAuthObjects,	TRequestStatus& aStatus) = 0;

 	/** 

 	 * Cancels an asynchronous List() operation.

 	 * 

 	 * The operation completes with KErrCancel. 

 	 */

 	virtual void CancelList() = 0;

 	};

 /**

  * The class returned as the token interface.

  * 

  * The class does not define any extra member functions or data. 

  */

 class MCTAuthenticationObjectList : public MCTTokenInterface, 

 									public MAuthenticationObjectList

 	{

 	};

 inline MCTAuthenticationObject::MCTAuthenticationObject(MCTToken& aToken)

 		: MCTTokenObject(aToken)

 	{

 	}

 #endif //__MCTAOSTORE_H__