--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/epoc32/include/ct/mcttoken.h Tue Mar 16 16:12:26 2010 +0000
@@ -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 <ct/tcttokenobjecthandle.h>
+#include <ct/mcttokenobject.h>
+#include <ct/tcttokenhandle.h>
+#include <ct/mcttokentype.h>
+
+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__