diff -r 675a964f4eb5 -r 35751d3474b7 cryptomgmtlibs/cryptotokenfw/inc/ct/MCTToken.h --- a/cryptomgmtlibs/cryptotokenfw/inc/ct/MCTToken.h Tue Jul 21 01:04:32 2009 +0100 +++ b/cryptomgmtlibs/cryptotokenfw/inc/ct/MCTToken.h Thu Sep 10 14:01:51 2009 +0300 @@ -1,248 +1,246 @@ -/* -* 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__ +/* +* 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__