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