/*
* 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__