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