epoc32/include/ct/mcttoken.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     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  @file
    21  @publishedAll
    22  @released
    23 */
    24 
    25 #ifndef __MCTTOKEN_H__
    26 #define __MCTTOKEN_H__
    27 
    28 #include <ct/tcttokenobjecthandle.h>
    29 #include <ct/mcttokenobject.h>
    30 #include <ct/tcttokenhandle.h>
    31 #include <ct/mcttokentype.h>
    32 
    33 class MCTTokenInterface;
    34 
    35 
    36 /** 
    37  * The base class for a token.
    38  * 
    39  * Token types must implement this class. It is created from a MCTTokenType using 
    40  * MCTTokenType::OpenToken().
    41  * 
    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.) 
    46  * 
    47  * @since v7.0 
    48  */
    49 class MCTToken
    50 	{
    51  public:
    52   //Functions for opening an interface. 
    53   //The base class implements the reference counting then calls the corresponding pure virtual Do... methods	
    54 	/** 
    55 	 * Gets a token interface, or NULL if it's not supported by this token.
    56 	 *
    57 	 * This is an asynchronous request.
    58 	 *
    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 
    61 	 * 								returned interface.
    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. 
    65 	 */
    66 	IMPORT_C void GetInterface(TUid aRequiredInterface,
    67 							  MCTTokenInterface*& aReturnedInterface, 
    68 							  TRequestStatus& aStatus);
    69 
    70 	/** 
    71 	 * Cancels an asynchronous GetInterface() operation.
    72 	 *
    73 	 * The operation completes with KErrCancel. 
    74 	 */
    75 	IMPORT_C void CancelGetInterface();
    76 	
    77 	/**
    78 	 * Allows the client to add a reference to the token (for
    79 	 * example, when a reference to a token is copied elsewhere).  
    80 	 * 
    81 	 * Does not need to be called if token is referenced through OpenToken().
    82 	 */
    83 	inline void AddRef();
    84 	
    85 	/** 
    86 	 * Destroys the object.
    87 	 *	
    88 	 * The interface should be destroyed via this method as the destructor is protected.
    89 	 *
    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.
    93 	 */
    94 	IMPORT_C void Release();
    95 
    96 	// Notification of token removal. The base class assumes the token is not removable, and so does nothing. Removable tokens must implement these functions.
    97 	/** 
    98 	 * Notifies the client when the token has been removed.
    99 	 *	
   100 	 * The base class assumes the token is not removable, and so does nothing. Removable 
   101 	 * tokens must implement these functions.
   102 	 *
   103 	 * This is an asynchronous request.	
   104 	 *
   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. 
   108 	 */
   109 	IMPORT_C virtual void NotifyOnRemoval(TRequestStatus& aStatus);
   110 
   111 	/** 
   112 	 * Cancels an asynchronous NotifyOnRemoval() operation.
   113 	 *
   114 	 * The operation completes with KErrCancel. 
   115 	 */
   116 	IMPORT_C virtual void CancelNotify();
   117 	
   118 
   119 	/** 
   120 	 * Gets the associated token type.	
   121 	 *
   122 	 * @return	The associated token type. 
   123 	 */
   124 	virtual MCTTokenType& TokenType() = 0;
   125 
   126 	/** 
   127 	 * Gets a label for the token.
   128 	 *
   129 	 * This should be the same as the descriptor returned by MCTTokenType::List().
   130 	 *
   131 	 * @return	The label to the token type. 
   132 	 */
   133 	virtual const TDesC& Label() = 0;
   134 
   135 	/** Available information strings for the token. */
   136 	enum TTokenInformation
   137 		{
   138 		/** Version */
   139 		EVersion,
   140 		/** Serial number */
   141 		ESerialNo,
   142 		/** Manufacturer */
   143 		EManufacturer
   144 		};
   145 	
   146 	/** 
   147 	 * Gets the token's handle.
   148 	 *
   149 	 * This can be used to identify a token to another process.
   150 	 *
   151 	 * See the documentation of TCTTokenHandle for an explanation of the use of token 
   152 	 * handles.
   153 	 *
   154 	 * @return	The handle of the token. 
   155 	 */
   156 	virtual TCTTokenHandle Handle() = 0;
   157 
   158  protected:
   159  	 /** 
   160  	  * The destructor is protected so that users of the interface
   161 	  * have to use the Release() function. 
   162 	  */
   163 	inline virtual ~MCTToken() = 0;
   164 
   165 	// Helper functions for the reference counting
   166 	/** 
   167 	 * Destroys the token object.
   168 	 *
   169 	 * This function is called when Release() has determined that the object is ready 
   170 	 * to be destroyed.
   171 	 *
   172 	 * The default implementation just does a 'delete this', but classes can override 
   173 	 * that if they want different behaviour.
   174 	 *
   175 	 * It should destroy the token; it MUST NOT release the token type, as Release() 
   176 	 * will do that. 
   177 	 */
   178 	IMPORT_C virtual void DoRelease();
   179 
   180 	/** 
   181 	 * Gets a reference to the variable used as a reference counter.
   182 	 *
   183 	 * The implementer should initialise this to 0. The value of the reference count 
   184 	 * should be treated as opaque by the implementer.
   185 	 *
   186 	 * @return	A reference to the variable used as a reference counter. 
   187 	 */
   188 	virtual TInt& ReferenceCount() = 0;
   189 	
   190 	// Implementation of GetInterface functionality */
   191 			
   192 	/** 
   193 	 * Implementation for getting a token interface.
   194 	 *
   195 	 * This is called by GetInterface().
   196 	 *
   197 	 * This is an asynchronous request.
   198 	 *
   199 	 * @see GetInterface
   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. 
   206 	 */
   207 	virtual void DoGetInterface(TUid aRequiredInterface,
   208 							  MCTTokenInterface*& aReturnedInterface, 
   209 							  TRequestStatus& aStatus) = 0;
   210 	/** 
   211 	 * Implements an asynchronous CancelGetInterface() request.
   212 	 * 
   213 	 * @see	CancelGetInterface
   214 	 * @return	ETrue if there is an token interface running; EFalse, otherwise. 
   215 	 */
   216 	virtual TBool DoCancelGetInterface() = 0;
   217 	
   218  private:
   219 	// Used by the token object to increment the reference count
   220 	void ObjectCreated();
   221 	// Needed to allow MCTTokenObject to increment the reference count
   222 	// of the token
   223 	friend class MCTTokenObject;
   224  public:
   225 	/**
   226 	 * Gets the specified information string about the token.
   227 	 * The default implementation returns an empty descriptor.
   228 	 */
   229 	virtual const TDesC& Information(TTokenInformation aRequiredInformation) = 0;
   230 	};
   231 
   232 /** 
   233  * Destructor.
   234  *
   235  * Frees all resources owned by the object, prior to its destruction. 
   236  */
   237 inline MCTToken::~MCTToken()
   238 	{
   239 	}
   240 
   241 inline void MCTToken::AddRef()
   242 	{
   243 	++ReferenceCount();
   244 	}
   245 
   246 #endif //__MCTTOKEN_H__