2 * Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
5 * under the terms of the License "Eclipse Public License v1.0"
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
25 #ifndef __MCTTOKEN_H__
26 #define __MCTTOKEN_H__
28 #include <ct/tcttokenobjecthandle.h>
29 #include <ct/mcttokenobject.h>
30 #include <ct/tcttokenhandle.h>
31 #include <ct/mcttokentype.h>
33 class MCTTokenInterface;
37 * The base class for a token.
39 * Token types must implement this class. It is created from a MCTTokenType using
40 * MCTTokenType::OpenToken().
42 * A token represents one instance of a particular kind of cryptographic module;
43 * for instance, on a device with two WIMs, each WIM is a token. The token contains
44 * several interfaces, representing particular kinds of functions supported by
45 * the token (e.g. certificate management, key management, etc.)
52 //Functions for opening an interface.
53 //The base class implements the reference counting then calls the corresponding pure virtual Do... methods
55 * Gets a token interface, or NULL if it's not supported by this token.
57 * This is an asynchronous request.
59 * @param aRequiredInterface The UID of the interface that should be returned.
60 * @param aReturnedInterface On success, this will be set to a pointer to the
62 * @param aStatus The request status object; contains the result of the
63 * GetInterface() request when complete. Set to KErrCancel
64 * if an outstanding request is cancelled.
66 IMPORT_C void GetInterface(TUid aRequiredInterface,
67 MCTTokenInterface*& aReturnedInterface,
68 TRequestStatus& aStatus);
71 * Cancels an asynchronous GetInterface() operation.
73 * The operation completes with KErrCancel.
75 IMPORT_C void CancelGetInterface();
78 * Allows the client to add a reference to the token (for
79 * example, when a reference to a token is copied elsewhere).
81 * Does not need to be called if token is referenced through OpenToken().
86 * Destroys the object.
88 * The interface should be destroyed via this method as the destructor is protected.
90 * The token implements reference counting, with one count
91 * for itself and one for every opened interface. Once the count
92 * reaches 0, it releases its count with the token type.
94 IMPORT_C void Release();
96 // Notification of token removal. The base class assumes the token is not removable, and so does nothing. Removable tokens must implement these functions.
98 * Notifies the client when the token has been removed.
100 * The base class assumes the token is not removable, and so does nothing. Removable
101 * tokens must implement these functions.
103 * This is an asynchronous request.
105 * @param aStatus The request status object; contains the result of the
106 * NotifyOnRemoval() request when complete. Set to KErrCancel
107 * if an outstanding request is cancelled.
109 IMPORT_C virtual void NotifyOnRemoval(TRequestStatus& aStatus);
112 * Cancels an asynchronous NotifyOnRemoval() operation.
114 * The operation completes with KErrCancel.
116 IMPORT_C virtual void CancelNotify();
120 * Gets the associated token type.
122 * @return The associated token type.
124 virtual MCTTokenType& TokenType() = 0;
127 * Gets a label for the token.
129 * This should be the same as the descriptor returned by MCTTokenType::List().
131 * @return The label to the token type.
133 virtual const TDesC& Label() = 0;
135 /** Available information strings for the token. */
136 enum TTokenInformation
147 * Gets the token's handle.
149 * This can be used to identify a token to another process.
151 * See the documentation of TCTTokenHandle for an explanation of the use of token
154 * @return The handle of the token.
156 virtual TCTTokenHandle Handle() = 0;
160 * The destructor is protected so that users of the interface
161 * have to use the Release() function.
163 inline virtual ~MCTToken() = 0;
165 // Helper functions for the reference counting
167 * Destroys the token object.
169 * This function is called when Release() has determined that the object is ready
172 * The default implementation just does a 'delete this', but classes can override
173 * that if they want different behaviour.
175 * It should destroy the token; it MUST NOT release the token type, as Release()
178 IMPORT_C virtual void DoRelease();
181 * Gets a reference to the variable used as a reference counter.
183 * The implementer should initialise this to 0. The value of the reference count
184 * should be treated as opaque by the implementer.
186 * @return A reference to the variable used as a reference counter.
188 virtual TInt& ReferenceCount() = 0;
190 // Implementation of GetInterface functionality */
193 * Implementation for getting a token interface.
195 * This is called by GetInterface().
197 * This is an asynchronous request.
200 * @param aRequiredInterface The UID of the interface that should be returned.
201 * @param aReturnedInterface On success, this will be set to a pointer to the
202 * returned interface.
203 * @param aStatus The request status object; contains the result of
204 * the GetInterface() request when complete. Set to
205 * KErrCancel if an outstanding request is cancelled.
207 virtual void DoGetInterface(TUid aRequiredInterface,
208 MCTTokenInterface*& aReturnedInterface,
209 TRequestStatus& aStatus) = 0;
211 * Implements an asynchronous CancelGetInterface() request.
213 * @see CancelGetInterface
214 * @return ETrue if there is an token interface running; EFalse, otherwise.
216 virtual TBool DoCancelGetInterface() = 0;
219 // Used by the token object to increment the reference count
220 void ObjectCreated();
221 // Needed to allow MCTTokenObject to increment the reference count
223 friend class MCTTokenObject;
226 * Gets the specified information string about the token.
227 * The default implementation returns an empty descriptor.
229 virtual const TDesC& Information(TTokenInformation aRequiredInformation) = 0;
235 * Frees all resources owned by the object, prior to its destruction.
237 inline MCTToken::~MCTToken()
241 inline void MCTToken::AddRef()
246 #endif //__MCTTOKEN_H__