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 williamr@2: #include williamr@2: #include williamr@2: #include 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__