epoc32/include/ct/mcttokentype.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 __MCTTOKENTYPE_H__
    26 #define __MCTTOKENTYPE_H__
    27 
    28 #include <f32file.h>
    29 #include <ct/rcpointerarray.h>
    30 
    31 class CCTTokenTypeInfo;
    32 class MCTToken;
    33 class TCTTokenHandle;
    34 
    35 
    36 /** 
    37  * A token type.
    38  *
    39  * This abstract class is instantiated using the ECom Plug-in Architecture 
    40  * for a particular token type. It allows a list of available tokens of that 
    41  * type to be obtained, and particular tokens to be opened.
    42  * 
    43  * All implementation classes are in fact a subclass of CCTTokenType; refer to 
    44  * its documentation for implementation details. Client access is entirely through 
    45  * this M class.
    46  * 
    47  * The difference betweeen a token type and a token is best explained with an 
    48  * example. Suppose a device has two identical WIM slots, the code to handle WIMs 
    49  * is one token type, which will have two tokens for the two WIMs. 
    50  *
    51  * @since v7.0 
    52  */
    53  class MCTTokenType
    54 	{
    55  public:
    56 	// Static constructor functions that use ECom to load the actual implementation.
    57 	/** 
    58 	 * Creates a MCTTokenType given it's CCTTokenTypeInfo
    59 	 *
    60 	 * The definition of this inline function is in CCTTokenType.h.  If you call
    61 	 * this function, you need to link against ctfinder.dll as well as
    62 	 * ctframework.dll
    63 	 *
    64 	 * @param aInfo	Information about the token type.
    65 	 * @param aFs	An open file server session.
    66 	 * @return		The new token type object. 
    67 	 */
    68 	inline static MCTTokenType* NewL(const CCTTokenTypeInfo& aInfo, RFs aFs);
    69 	
    70 	/** 
    71 	 * Creates a MCTTokenType given the UID of the token type. 
    72 	 *
    73 	 * The definition of this inline function is in CCTTokenType.h.  If you call
    74 	 * this function, you need to link against ctfinder.dll as well as
    75 	 * ctframework.dll
    76 	 *
    77 	 * @param aUID	The UID of the token type.
    78 	 * @param aFs	An open file server session.
    79 	 * @return		A new token type object. 
    80 	 */
    81 	inline static MCTTokenType* NewL(TUid aUID, RFs aFs);
    82 	
    83 	/** 
    84 	 * Lists all the tokens of this type.
    85 	 *
    86 	 * This is an asynchronous request.
    87 	 *
    88 	 * Tokens are defined by name, so instead of returning a CCTTokenTypeInfo object, 
    89 	 * this function just gives a list of pointers to HBufC objects.
    90 	 *
    91 	 * @param aTokens	On return, a list of all the tokens.
    92 	 * @param aStatus	The request status object; contains the result of the List() 
    93 	 * 					request when complete. Set to KErrCancel if an outstanding request is cancelled. 
    94 	 */
    95 	virtual void List(RCPointerArray<HBufC>& aTokens, 
    96 					  TRequestStatus& aStatus) = 0;
    97 	
    98 	/** 
    99 	 * Cancels an asynchronous List() operation.
   100 	 *
   101 	 * The operation completes with KErrCancel. 
   102 	 */
   103 	virtual void CancelList() = 0;
   104 	
   105 	/** 
   106 	 * Opens the specified token.	
   107 	 *
   108 	 * @param aTokenInfo	Information about the required token.
   109 	 * @param aToken		On return, the token to be opened.
   110 	 * @param aStatus		The request status object; contains the result of the OpenToken() 
   111 	 * 						request when complete. Set to KErrCancel if an outstanding request is cancelled. 
   112 	 */
   113 	virtual void OpenToken(const TDesC& aTokenInfo, MCTToken*& aToken, 
   114 						   TRequestStatus& aStatus) = 0;
   115 	
   116 	/** 
   117 	 * Opens the specified token. 	
   118 	 *
   119 	 * @param aHandle	The handle of the token.
   120 	 * @param aToken	On return, the token to be opened.
   121 	 * @param aStatus	The request status object; contains the result of the OpenToken() 
   122 	 * 					request when complete. Set to KErrCancel if an outstanding request is cancelled. 
   123 	 */
   124 	virtual void OpenToken(TCTTokenHandle aHandle, MCTToken*& aToken, 
   125 						   TRequestStatus& aStatus) = 0;
   126 
   127 	/** 
   128 	 * Cancels an asynchronous OpenToken() operation.
   129 	 *
   130 	 * The operation completes with KErrCancel. 
   131 	 */
   132 	virtual void CancelOpenToken() = 0;
   133 	
   134 	/** 
   135 	 * Releases the token type object.
   136 	 *
   137 	 * To be called when you have finished with the object.
   138 	 *
   139 	 * The API does not allow the destructor to be directly called as this object 
   140 	 * could remain in existence for longer to hold onto the ECom handle on the DLL; 
   141 	 * for instance, it may not be deleted until all tokens and interfaces have also 
   142 	 * been released. 
   143 	 */
   144 	virtual void Release() = 0;
   145 
   146 	/** 
   147 	 * Gets the UID of the token type.
   148 	 *
   149 	 * This function is implemented by CCTTokenType, so token type implementers need 
   150 	 * not implement it.
   151 	 *
   152 	 * @return	The UID of the token type. 
   153 	 */
   154 	virtual TUid Type() const = 0;
   155 
   156 	/** 
   157 	 * Gets the label of the token type.
   158 	 *
   159 	 * This function is implemented by CCTTokenType, so token type implementers need 
   160 	 * not implement it.
   161 	 *
   162 	 * @return	The label to the token type. 
   163 	 */
   164 	virtual const TDesC& Label() const = 0;
   165 	};
   166 
   167 #endif //__MCTTOKENTYPE_H__