/*

 * 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 __MCTTOKEN_H__

 #define __MCTTOKEN_H__

 #include <ct/tcttokenobjecthandle.h>

 #include <ct/mcttokenobject.h>

 #include <ct/tcttokenhandle.h>

 #include <ct/mcttokentype.h>

 class MCTTokenInterface;

 /** 

  * The base class for a token.

  * 

  * Token types must implement this class. It is created from a MCTTokenType using 

  * MCTTokenType::OpenToken().

  * 

  * A token represents one instance of a particular kind of cryptographic module; 

  * for instance, on a device with two WIMs, each WIM is a token. The token contains 

  * several interfaces, representing particular kinds of functions supported by 

  * the token (e.g. certificate management, key management, etc.) 

  * 

  * @since v7.0 

  */

 class MCTToken

 	{

  public:

   //Functions for opening an interface. 

   //The base class implements the reference counting then calls the corresponding pure virtual Do... methods	

 	/** 

 	 * Gets a token interface, or NULL if it's not supported by this token.

 	 *

 	 * This is an asynchronous request.

 	 *

 	 * @param aRequiredInterface	The UID of the interface that should be returned.

 	 * @param aReturnedInterface	On success, this will be set to a pointer to the 

 	 * 								returned interface.

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

 	 * 								GetInterface() request when complete. Set to KErrCancel 

 	 * 								if an outstanding request is cancelled. 

 	 */

 	IMPORT_C void GetInterface(TUid aRequiredInterface,

 							  MCTTokenInterface*& aReturnedInterface, 

 							  TRequestStatus& aStatus);

 	/** 

 	 * Cancels an asynchronous GetInterface() operation.

 	 *

 	 * The operation completes with KErrCancel. 

 	 */

 	IMPORT_C void CancelGetInterface();

 	/**

 	 * Allows the client to add a reference to the token (for

 	 * example, when a reference to a token is copied elsewhere).  

 	 * 

 	 * Does not need to be called if token is referenced through OpenToken().

 	 */

 	inline void AddRef();

 	/** 

 	 * Destroys the object.

 	 *	

 	 * The interface should be destroyed via this method as the destructor is protected.

 	 *

 	 * The token implements reference counting, with one count

 	 * for itself and one for every opened interface. Once the count

 	 * reaches 0, it releases its count with the token type.

 	 */

 	IMPORT_C void Release();

 	// Notification of token removal. The base class assumes the token is not removable, and so does nothing. Removable tokens must implement these functions.

 	/** 

 	 * Notifies the client when the token has been removed.

 	 *	

 	 * The base class assumes the token is not removable, and so does nothing. Removable 

 	 * tokens must implement these functions.

 	 *

 	 * This is an asynchronous request.	

 	 *

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

 	 * 					NotifyOnRemoval() request when complete. Set to KErrCancel 

 	 * 					if an outstanding request is cancelled. 

 	 */

 	IMPORT_C virtual void NotifyOnRemoval(TRequestStatus& aStatus);

 	/** 

 	 * Cancels an asynchronous NotifyOnRemoval() operation.

 	 *

 	 * The operation completes with KErrCancel. 

 	 */

 	IMPORT_C virtual void CancelNotify();

 	/** 

 	 * Gets the associated token type.	

 	 *

 	 * @return	The associated token type. 

 	 */

 	virtual MCTTokenType& TokenType() = 0;

 	/** 

 	 * Gets a label for the token.

 	 *

 	 * This should be the same as the descriptor returned by MCTTokenType::List().

 	 *

 	 * @return	The label to the token type. 

 	 */

 	virtual const TDesC& Label() = 0;

 	/** Available information strings for the token. */

 	enum TTokenInformation

 		{

 		/** Version */

 		EVersion,

 		/** Serial number */

 		ESerialNo,

 		/** Manufacturer */

 		EManufacturer

 		};

 	/** 

 	 * Gets the token's handle.

 	 *

 	 * This can be used to identify a token to another process.

 	 *

 	 * See the documentation of TCTTokenHandle for an explanation of the use of token 

 	 * handles.

 	 *

 	 * @return	The handle of the token. 

 	 */

 	virtual TCTTokenHandle Handle() = 0;

  protected:

  	 /** 

  	  * The destructor is protected so that users of the interface

 	  * have to use the Release() function. 

 	  */

 	inline virtual ~MCTToken() = 0;

 	// Helper functions for the reference counting

 	/** 

 	 * Destroys the token object.

 	 *

 	 * This function is called when Release() has determined that the object is ready 

 	 * to be destroyed.

 	 *

 	 * The default implementation just does a 'delete this', but classes can override 

 	 * that if they want different behaviour.

 	 *

 	 * It should destroy the token; it MUST NOT release the token type, as Release() 

 	 * will do that. 

 	 */

 	IMPORT_C virtual void DoRelease();

 	/** 

 	 * Gets a reference to the variable used as a reference counter.

 	 *

 	 * The implementer should initialise this to 0. The value of the reference count 

 	 * should be treated as opaque by the implementer.

 	 *

 	 * @return	A reference to the variable used as a reference counter. 

 	 */

 	virtual TInt& ReferenceCount() = 0;

 	// Implementation of GetInterface functionality */

 	/** 

 	 * Implementation for getting a token interface.

 	 *

 	 * This is called by GetInterface().

 	 *

 	 * This is an asynchronous request.

 	 *

 	 * @see GetInterface

 	 * @param aRequiredInterface	The UID of the interface that should be returned.

 	 * @param aReturnedInterface	On success, this will be set to a pointer to the 

 	 * 								returned interface.

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

 	 * 								the GetInterface() request when complete. Set to 

 	 * 								KErrCancel if an outstanding request is cancelled. 

 	 */

 	virtual void DoGetInterface(TUid aRequiredInterface,

 							  MCTTokenInterface*& aReturnedInterface, 

 							  TRequestStatus& aStatus) = 0;

 	/** 

 	 * Implements an asynchronous CancelGetInterface() request.

 	 * 

 	 * @see	CancelGetInterface

 	 * @return	ETrue if there is an token interface running; EFalse, otherwise. 

 	 */

 	virtual TBool DoCancelGetInterface() = 0;

  private:

 	// Used by the token object to increment the reference count

 	void ObjectCreated();

 	// Needed to allow MCTTokenObject to increment the reference count

 	// of the token

 	friend class MCTTokenObject;

  public:

 	/**

 	 * Gets the specified information string about the token.

 	 * The default implementation returns an empty descriptor.

 	 */

 	virtual const TDesC& Information(TTokenInformation aRequiredInformation) = 0;

 	};

 /** 

  * Destructor.

  *

  * Frees all resources owned by the object, prior to its destruction. 

  */

 inline MCTToken::~MCTToken()

 	{

 	}

 inline void MCTToken::AddRef()

 	{

 	++ReferenceCount();

 	}

 #endif //__MCTTOKEN_H__