1 /*

     2 * Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     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".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 /**

    22  @file

    23  @publishedPartner

    24  @released

    25 */

    26 

    27 #ifndef __MCTTOKEN_H__

    28 #define __MCTTOKEN_H__

    29 

    30 #include <ct/tcttokenobjecthandle.h>

    31 #include <ct/mcttokenobject.h>

    32 #include <ct/tcttokenhandle.h>

    33 #include <ct/mcttokentype.h>

    34 

    35 class MCTTokenInterface;

    36 

    37 

    38 /** 

    39  * The base class for a token.

    40  * 

    41  * Token types must implement this class. It is created from a MCTTokenType using 

    42  * MCTTokenType::OpenToken().

    43  * 

    44  * A token represents one instance of a particular kind of cryptographic module; 

    45  * for instance, on a device with two WIMs, each WIM is a token. The token contains 

    46  * several interfaces, representing particular kinds of functions supported by 

    47  * the token (e.g. certificate management, key management, etc.) 

    48  * 

    49  * @since v7.0 

    50  */

    51 class MCTToken

    52 	{

    53  public:

    54   //Functions for opening an interface. 

    55   //The base class implements the reference counting then calls the corresponding pure virtual Do... methods	

    56 	/** 

    57 	 * Gets a token interface, or NULL if it's not supported by this token.

    58 	 *

    59 	 * This is an asynchronous request.

    60 	 *

    61 	 * @param aRequiredInterface	The UID of the interface that should be returned.

    62 	 * @param aReturnedInterface	On success, this will be set to a pointer to the 

    63 	 * 								returned interface.

    64 	 * @param aStatus				The request status object; contains the result of the 

    65 	 * 								GetInterface() request when complete. Set to KErrCancel 

    66 	 * 								if an outstanding request is cancelled. 

    67 	 */

    68 	IMPORT_C void GetInterface(TUid aRequiredInterface,

    69 							  MCTTokenInterface*& aReturnedInterface, 

    70 							  TRequestStatus& aStatus);

    71 

    72 	/** 

    73 	 * Cancels an asynchronous GetInterface() operation.

    74 	 *

    75 	 * The operation completes with KErrCancel. 

    76 	 */

    77 	IMPORT_C void CancelGetInterface();

    78 	

    79 	/**

    80 	 * Allows the client to add a reference to the token (for

    81 	 * example, when a reference to a token is copied elsewhere).  

    82 	 * 

    83 	 * Does not need to be called if token is referenced through OpenToken().

    84 	 */

    85 	inline void AddRef();

    86 	

    87 	/** 

    88 	 * Destroys the object.

    89 	 *	

    90 	 * The interface should be destroyed via this method as the destructor is protected.

    91 	 *

    92 	 * The token implements reference counting, with one count

    93 	 * for itself and one for every opened interface. Once the count

    94 	 * reaches 0, it releases its count with the token type.

    95 	 */

    96 	IMPORT_C void Release();

    97 

    98 	// Notification of token removal. The base class assumes the token is not removable, and so does nothing. Removable tokens must implement these functions.

    99 	/** 

   100 	 * Notifies the client when the token has been removed.

   101 	 *	

   102 	 * The base class assumes the token is not removable, and so does nothing. Removable 

   103 	 * tokens must implement these functions.

   104 	 *

   105 	 * This is an asynchronous request.	

   106 	 *

   107 	 * @param aStatus	The request status object; contains the result of the 

   108 	 * 					NotifyOnRemoval() request when complete. Set to KErrCancel 

   109 	 * 					if an outstanding request is cancelled. 

   110 	 */

   111 	IMPORT_C virtual void NotifyOnRemoval(TRequestStatus& aStatus);

   112 

   113 	/** 

   114 	 * Cancels an asynchronous NotifyOnRemoval() operation.

   115 	 *

   116 	 * The operation completes with KErrCancel. 

   117 	 */

   118 	IMPORT_C virtual void CancelNotify();

   119 	

   120 

   121 	/** 

   122 	 * Gets the associated token type.	

   123 	 *

   124 	 * @return	The associated token type. 

   125 	 */

   126 	virtual MCTTokenType& TokenType() = 0;

   127 

   128 	/** 

   129 	 * Gets a label for the token.

   130 	 *

   131 	 * This should be the same as the descriptor returned by MCTTokenType::List().

   132 	 *

   133 	 * @return	The label to the token type. 

   134 	 */

   135 	virtual const TDesC& Label() = 0;

   136 

   137 	/** Available information strings for the token. */

   138 	enum TTokenInformation

   139 		{

   140 		/** Version */

   141 		EVersion,

   142 		/** Serial number */

   143 		ESerialNo,

   144 		/** Manufacturer */

   145 		EManufacturer

   146 		};

   147 	

   148 	/** 

   149 	 * Gets the token's handle.

   150 	 *

   151 	 * This can be used to identify a token to another process.

   152 	 *

   153 	 * See the documentation of TCTTokenHandle for an explanation of the use of token 

   154 	 * handles.

   155 	 *

   156 	 * @return	The handle of the token. 

   157 	 */

   158 	virtual TCTTokenHandle Handle() = 0;

   159 

   160  protected:

   161  	 /** 

   162  	  * The destructor is protected so that users of the interface

   163 	  * have to use the Release() function. 

   164 	  */

   165 	inline virtual ~MCTToken() = 0;

   166 

   167 	// Helper functions for the reference counting

   168 	/** 

   169 	 * Destroys the token object.

   170 	 *

   171 	 * This function is called when Release() has determined that the object is ready 

   172 	 * to be destroyed.

   173 	 *

   174 	 * The default implementation just does a 'delete this', but classes can override 

   175 	 * that if they want different behaviour.

   176 	 *

   177 	 * It should destroy the token; it MUST NOT release the token type, as Release() 

   178 	 * will do that. 

   179 	 */

   180 	IMPORT_C virtual void DoRelease();

   181 

   182 	/** 

   183 	 * Gets a reference to the variable used as a reference counter.

   184 	 *

   185 	 * The implementer should initialise this to 0. The value of the reference count 

   186 	 * should be treated as opaque by the implementer.

   187 	 *

   188 	 * @return	A reference to the variable used as a reference counter. 

   189 	 */

   190 	virtual TInt& ReferenceCount() = 0;

   191 	

   192 	// Implementation of GetInterface functionality */

   193 			

   194 	/** 

   195 	 * Implementation for getting a token interface.

   196 	 *

   197 	 * This is called by GetInterface().

   198 	 *

   199 	 * This is an asynchronous request.

   200 	 *

   201 	 * @see GetInterface

   202 	 * @param aRequiredInterface	The UID of the interface that should be returned.

   203 	 * @param aReturnedInterface	On success, this will be set to a pointer to the 

   204 	 * 								returned interface.

   205 	 * @param aStatus				The request status object; contains the result of 

   206 	 * 								the GetInterface() request when complete. Set to 

   207 	 * 								KErrCancel if an outstanding request is cancelled. 

   208 	 */

   209 	virtual void DoGetInterface(TUid aRequiredInterface,

   210 							  MCTTokenInterface*& aReturnedInterface, 

   211 							  TRequestStatus& aStatus) = 0;

   212 	/** 

   213 	 * Implements an asynchronous CancelGetInterface() request.

   214 	 * 

   215 	 * @see	CancelGetInterface

   216 	 * @return	ETrue if there is an token interface running; EFalse, otherwise. 

   217 	 */

   218 	virtual TBool DoCancelGetInterface() = 0;

   219 	

   220  private:

   221 	// Used by the token object to increment the reference count

   222 	void ObjectCreated();

   223 	// Needed to allow MCTTokenObject to increment the reference count

   224 	// of the token

   225 	friend class MCTTokenObject;

   226  public:

   227 	/**

   228 	 * Gets the specified information string about the token.

   229 	 * The default implementation returns an empty descriptor.

   230 	 */

   231 	virtual const TDesC& Information(TTokenInformation aRequiredInformation) = 0;

   232 	};

   233 

   234 /** 

   235  * Destructor.

   236  *

   237  * Frees all resources owned by the object, prior to its destruction. 

   238  */

   239 inline MCTToken::~MCTToken()

   240 	{

   241 	}

   242 

   243 inline void MCTToken::AddRef()

   244 	{

   245 	++ReferenceCount();

   246 	}

   247 

   248 #endif //__MCTTOKEN_H__