diff -r 000000000000 -r 2c201484c85f cryptomgmtlibs/cryptotokenfw/inc/ct/MCTToken.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/cryptomgmtlibs/cryptotokenfw/inc/ct/MCTToken.h Wed Jul 08 11:25:26 2009 +0100 @@ -0,0 +1,248 @@ +/* +* 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 +#include +#include +#include + +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__