williamr@2: /*
williamr@2: * Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * under the terms of the License "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description: 
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2:  @file
williamr@2:  @publishedPartner
williamr@2:  @released
williamr@2: */
williamr@2: 
williamr@2: #ifndef __MCTTOKEN_H__
williamr@2: #define __MCTTOKEN_H__
williamr@2: 
williamr@2: #include <ct/tcttokenobjecthandle.h>
williamr@2: #include <ct/mcttokenobject.h>
williamr@2: #include <ct/tcttokenhandle.h>
williamr@2: #include <ct/mcttokentype.h>
williamr@2: 
williamr@2: class MCTTokenInterface;
williamr@2: 
williamr@2: 
williamr@2: /** 
williamr@2:  * The base class for a token.
williamr@2:  * 
williamr@2:  * Token types must implement this class. It is created from a MCTTokenType using 
williamr@2:  * MCTTokenType::OpenToken().
williamr@2:  * 
williamr@2:  * A token represents one instance of a particular kind of cryptographic module; 
williamr@2:  * for instance, on a device with two WIMs, each WIM is a token. The token contains 
williamr@2:  * several interfaces, representing particular kinds of functions supported by 
williamr@2:  * the token (e.g. certificate management, key management, etc.) 
williamr@2:  * 
williamr@2:  * @since v7.0 
williamr@2:  */
williamr@2: class MCTToken
williamr@2: 	{
williamr@2:  public:
williamr@2:   //Functions for opening an interface. 
williamr@2:   //The base class implements the reference counting then calls the corresponding pure virtual Do... methods	
williamr@2: 	/** 
williamr@2: 	 * Gets a token interface, or NULL if it's not supported by this token.
williamr@2: 	 *
williamr@2: 	 * This is an asynchronous request.
williamr@2: 	 *
williamr@2: 	 * @param aRequiredInterface	The UID of the interface that should be returned.
williamr@2: 	 * @param aReturnedInterface	On success, this will be set to a pointer to the 
williamr@2: 	 * 								returned interface.
williamr@2: 	 * @param aStatus				The request status object; contains the result of the 
williamr@2: 	 * 								GetInterface() request when complete. Set to KErrCancel 
williamr@2: 	 * 								if an outstanding request is cancelled. 
williamr@2: 	 */
williamr@2: 	IMPORT_C void GetInterface(TUid aRequiredInterface,
williamr@2: 							  MCTTokenInterface*& aReturnedInterface, 
williamr@2: 							  TRequestStatus& aStatus);
williamr@2: 
williamr@2: 	/** 
williamr@2: 	 * Cancels an asynchronous GetInterface() operation.
williamr@2: 	 *
williamr@2: 	 * The operation completes with KErrCancel. 
williamr@2: 	 */
williamr@2: 	IMPORT_C void CancelGetInterface();
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 * Allows the client to add a reference to the token (for
williamr@2: 	 * example, when a reference to a token is copied elsewhere).  
williamr@2: 	 * 
williamr@2: 	 * Does not need to be called if token is referenced through OpenToken().
williamr@2: 	 */
williamr@2: 	inline void AddRef();
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	 * Destroys the object.
williamr@2: 	 *	
williamr@2: 	 * The interface should be destroyed via this method as the destructor is protected.
williamr@2: 	 *
williamr@2: 	 * The token implements reference counting, with one count
williamr@2: 	 * for itself and one for every opened interface. Once the count
williamr@2: 	 * reaches 0, it releases its count with the token type.
williamr@2: 	 */
williamr@2: 	IMPORT_C void Release();
williamr@2: 
williamr@2: 	// Notification of token removal. The base class assumes the token is not removable, and so does nothing. Removable tokens must implement these functions.
williamr@2: 	/** 
williamr@2: 	 * Notifies the client when the token has been removed.
williamr@2: 	 *	
williamr@2: 	 * The base class assumes the token is not removable, and so does nothing. Removable 
williamr@2: 	 * tokens must implement these functions.
williamr@2: 	 *
williamr@2: 	 * This is an asynchronous request.	
williamr@2: 	 *
williamr@2: 	 * @param aStatus	The request status object; contains the result of the 
williamr@2: 	 * 					NotifyOnRemoval() request when complete. Set to KErrCancel 
williamr@2: 	 * 					if an outstanding request is cancelled. 
williamr@2: 	 */
williamr@2: 	IMPORT_C virtual void NotifyOnRemoval(TRequestStatus& aStatus);
williamr@2: 
williamr@2: 	/** 
williamr@2: 	 * Cancels an asynchronous NotifyOnRemoval() operation.
williamr@2: 	 *
williamr@2: 	 * The operation completes with KErrCancel. 
williamr@2: 	 */
williamr@2: 	IMPORT_C virtual void CancelNotify();
williamr@2: 	
williamr@2: 
williamr@2: 	/** 
williamr@2: 	 * Gets the associated token type.	
williamr@2: 	 *
williamr@2: 	 * @return	The associated token type. 
williamr@2: 	 */
williamr@2: 	virtual MCTTokenType& TokenType() = 0;
williamr@2: 
williamr@2: 	/** 
williamr@2: 	 * Gets a label for the token.
williamr@2: 	 *
williamr@2: 	 * This should be the same as the descriptor returned by MCTTokenType::List().
williamr@2: 	 *
williamr@2: 	 * @return	The label to the token type. 
williamr@2: 	 */
williamr@2: 	virtual const TDesC& Label() = 0;
williamr@2: 
williamr@2: 	/** Available information strings for the token. */
williamr@2: 	enum TTokenInformation
williamr@2: 		{
williamr@2: 		/** Version */
williamr@2: 		EVersion,
williamr@2: 		/** Serial number */
williamr@2: 		ESerialNo,
williamr@2: 		/** Manufacturer */
williamr@2: 		EManufacturer
williamr@2: 		};
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	 * Gets the token's handle.
williamr@2: 	 *
williamr@2: 	 * This can be used to identify a token to another process.
williamr@2: 	 *
williamr@2: 	 * See the documentation of TCTTokenHandle for an explanation of the use of token 
williamr@2: 	 * handles.
williamr@2: 	 *
williamr@2: 	 * @return	The handle of the token. 
williamr@2: 	 */
williamr@2: 	virtual TCTTokenHandle Handle() = 0;
williamr@2: 
williamr@2:  protected:
williamr@2:  	 /** 
williamr@2:  	  * The destructor is protected so that users of the interface
williamr@2: 	  * have to use the Release() function. 
williamr@2: 	  */
williamr@2: 	inline virtual ~MCTToken() = 0;
williamr@2: 
williamr@2: 	// Helper functions for the reference counting
williamr@2: 	/** 
williamr@2: 	 * Destroys the token object.
williamr@2: 	 *
williamr@2: 	 * This function is called when Release() has determined that the object is ready 
williamr@2: 	 * to be destroyed.
williamr@2: 	 *
williamr@2: 	 * The default implementation just does a 'delete this', but classes can override 
williamr@2: 	 * that if they want different behaviour.
williamr@2: 	 *
williamr@2: 	 * It should destroy the token; it MUST NOT release the token type, as Release() 
williamr@2: 	 * will do that. 
williamr@2: 	 */
williamr@2: 	IMPORT_C virtual void DoRelease();
williamr@2: 
williamr@2: 	/** 
williamr@2: 	 * Gets a reference to the variable used as a reference counter.
williamr@2: 	 *
williamr@2: 	 * The implementer should initialise this to 0. The value of the reference count 
williamr@2: 	 * should be treated as opaque by the implementer.
williamr@2: 	 *
williamr@2: 	 * @return	A reference to the variable used as a reference counter. 
williamr@2: 	 */
williamr@2: 	virtual TInt& ReferenceCount() = 0;
williamr@2: 	
williamr@2: 	// Implementation of GetInterface functionality */
williamr@2: 			
williamr@2: 	/** 
williamr@2: 	 * Implementation for getting a token interface.
williamr@2: 	 *
williamr@2: 	 * This is called by GetInterface().
williamr@2: 	 *
williamr@2: 	 * This is an asynchronous request.
williamr@2: 	 *
williamr@2: 	 * @see GetInterface
williamr@2: 	 * @param aRequiredInterface	The UID of the interface that should be returned.
williamr@2: 	 * @param aReturnedInterface	On success, this will be set to a pointer to the 
williamr@2: 	 * 								returned interface.
williamr@2: 	 * @param aStatus				The request status object; contains the result of 
williamr@2: 	 * 								the GetInterface() request when complete. Set to 
williamr@2: 	 * 								KErrCancel if an outstanding request is cancelled. 
williamr@2: 	 */
williamr@2: 	virtual void DoGetInterface(TUid aRequiredInterface,
williamr@2: 							  MCTTokenInterface*& aReturnedInterface, 
williamr@2: 							  TRequestStatus& aStatus) = 0;
williamr@2: 	/** 
williamr@2: 	 * Implements an asynchronous CancelGetInterface() request.
williamr@2: 	 * 
williamr@2: 	 * @see	CancelGetInterface
williamr@2: 	 * @return	ETrue if there is an token interface running; EFalse, otherwise. 
williamr@2: 	 */
williamr@2: 	virtual TBool DoCancelGetInterface() = 0;
williamr@2: 	
williamr@2:  private:
williamr@2: 	// Used by the token object to increment the reference count
williamr@2: 	void ObjectCreated();
williamr@2: 	// Needed to allow MCTTokenObject to increment the reference count
williamr@2: 	// of the token
williamr@2: 	friend class MCTTokenObject;
williamr@2:  public:
williamr@2: 	/**
williamr@2: 	 * Gets the specified information string about the token.
williamr@2: 	 * The default implementation returns an empty descriptor.
williamr@2: 	 */
williamr@2: 	virtual const TDesC& Information(TTokenInformation aRequiredInformation) = 0;
williamr@2: 	};
williamr@2: 
williamr@2: /** 
williamr@2:  * Destructor.
williamr@2:  *
williamr@2:  * Frees all resources owned by the object, prior to its destruction. 
williamr@2:  */
williamr@2: inline MCTToken::~MCTToken()
williamr@2: 	{
williamr@2: 	}
williamr@2: 
williamr@2: inline void MCTToken::AddRef()
williamr@2: 	{
williamr@2: 	++ReferenceCount();
williamr@2: 	}
williamr@2: 
williamr@2: #endif //__MCTTOKEN_H__