[mirror_edk2.git] / MdePkg / Include / Protocol / SmartCardReader.h

/** @file\r
  The UEFI Smart Card Reader Protocol provides an abstraction for device to provide\r
  smart card reader support. This protocol is very close to Part 5 of PC/SC workgroup\r
  specifications and provides an API to applications willing to communicate with a\r
  smart card or a smart card reader.\r
\r
  Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __SMART_CARD_READER_H__\r
#define __SMART_CARD_READER_H__\r
\r
#define EFI_SMART_CARD_READER_PROTOCOL_GUID \\r
    { \\r
      0x2a4d1adf, 0x21dc, 0x4b81, {0xa4, 0x2f, 0x8b, 0x8e, 0xe2, 0x38, 0x00, 0x60} \\r
    }\r
\r
typedef struct _EFI_SMART_CARD_READER_PROTOCOL  EFI_SMART_CARD_READER_PROTOCOL;\r
\r
//\r
// Codes for access mode\r
//\r
#define SCARD_AM_READER              0x0001 // Exclusive access to reader\r
#define SCARD_AM_CARD                0x0002 // Exclusive access to card\r
//\r
// Codes for card action\r
//\r
#define SCARD_CA_NORESET             0x0000 // Don't reset card\r
#define SCARD_CA_COLDRESET           0x0001 // Perform a cold reset\r
#define SCARD_CA_WARMRESET           0x0002 // Perform a warm reset\r
#define SCARD_CA_UNPOWER             0x0003 // Power off the card\r
#define SCARD_CA_EJECT               0x0004 // Eject the card\r
//\r
// Protocol types\r
//\r
#define SCARD_PROTOCOL_UNDEFINED     0x0000\r
#define SCARD_PROTOCOL_T0            0x0001\r
#define SCARD_PROTOCOL_T1            0x0002\r
#define SCARD_PROTOCOL_RAW           0x0004\r
//\r
// Codes for state type\r
//\r
#define SCARD_UNKNOWN                0x0000 /* state is unknown */\r
#define SCARD_ABSENT                 0x0001 /* Card is absent */\r
#define SCARD_INACTIVE               0x0002 /* Card is present and not powered*/\r
#define SCARD_ACTIVE                 0x0003 /* Card is present and powered */\r
//\r
// Macro to generate a ControlCode & PC/SC part 10 control code\r
//\r
#define SCARD_CTL_CODE(code)         (0x42000000 + (code))\r
#define CM_IOCTL_GET_FEATURE_REQUEST SCARD_CTL_CODE(3400)\r
\r
/**\r
  This function requests connection to the smart card or the reader, using the\r
  appropriate reset type and protocol.\r
\r
  The SCardConnectfunction requests access to the smart card or the reader. Upon\r
  success, it is then possible to call SCardTransmit.\r
\r
  If AccessMode is set to SCARD_AM_READER, PreferredProtocols must be set to\r
  SCARD_PROTOCOL_UNDEFINED and CardAction to SCARD_CA_NORESET else function\r
  fails with EFI_INVALID_PARAMETER.\r
\r
  @param[in]  This               Indicates a pointer to the calling context.\r
  @param[in]  AccessMode         Codes of access mode.\r
  @param[in]  CardAction         SCARD_CA_NORESET, SCARD_CA_COLDRESET or\r
                                 SCARD_CA_WARMRESET.\r
  @param[in]  PreferredProtocols Bitmask of acceptable protocols.\r
  @param[out] ActiveProtocol     A flag that indicates the active protocol.\r
\r
  @retval EFI_SUCCESS            The requested command completed successfully.\r
  @retval EFI_INVALID_PARAMETER  This is NULL\r
  @retval EFI_INVALID_PARAMETER  AccessMode is not valid.\r
  @retval EFI_INVALID_PARAMETER  CardAction is not valid.\r
  @retval EFI_INVALID_PARAMETER  Invalid combination of AccessMode/CardAction/\r
                                 PreferredProtocols.\r
  @retval EFI_NOT_READY          A smart card is inserted but failed to return an ATR.\r
  @retval EFI_UNSUPPORTED        PreferredProtocols does not contain an available\r
                                 protocol to use.\r
  @retval EFI_NO_MEDIA           AccessMode is set to SCARD_AM_CARD but there is\r
                                 no smart card inserted.\r
  @retval EFI_ACCESS_DENIED      Access is already locked by a previous SCardConnectcall.\r
  @retval EFI_DEVICE_ERROR       Any other error condition, typically a reader removal.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SMART_CARD_READER_CONNECT) (\r
  IN     EFI_SMART_CARD_READER_PROTOCOL    *This,\r
  IN     UINT32                            AccessMode,\r
  IN     UINT32                            CardAction,\r
  IN     UINT32                            PreferredProtocols,\r
     OUT UINT32                            *ActiveProtocol\r
  );\r
\r
/**\r
  This function releases a connection previously taken by SCardConnect.\r
\r
  The SCardDisconnect function releases the lock previously taken by SCardConnect.\r
  In case the smart card has been removed before this call, thisfunction\r
  returns EFI_SUCCESS. If there is no previous call to SCardConnect, this\r
  function returns EFI_SUCCESS.\r
\r
  @param[in]  This               Indicates a pointer to the calling context.\r
  @param[in]  CardAction         Codes for card action.\r
\r
  @retval EFI_SUCCESS            The requested command completed successfully.\r
  @retval EFI_INVALID_PARAMETER  This is NULL\r
  @retval EFI_INVALID_PARAMETER  CardAction value is unknown.\r
  @retval EFI_UNSUPPORTED        Reader does not support Eject card feature\r
                                 (disconnect was not performed).\r
  @retval EFI_DEVICE_ERROR       Any other error condition, typically a reader removal.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SMART_CARD_READER_DISCONNECT) (\r
  IN  EFI_SMART_CARD_READER_PROTOCOL    *This,\r
  IN  UINT32                            CardAction\r
  );\r
\r
/**\r
  This function retrieves some basic information about the smart card and reader.\r
\r
  The SCardStatusfunction retrieves basic reader and card information.\r
\r
  If ReaderName, State, CardProtocolor Atris NULL, the function does not fail but\r
  does not fill in such variables.\r
\r
  If EFI_SUCCESS is not returned, ReaderName and Atr contents shall not be considered\r
  as valid.\r
\r
  @param[in]      This             Indicates a pointer to the calling context.\r
  @param[out]     ReaderName       A pointer to a NULL terminated string that will\r
                                   contain the reader name.\r
  @param[in, out] ReaderNameLength On input, a pointer to the variablethat holds the\r
                                   maximal size, in bytes,of ReaderName.\r
                                   On output, the required size, in bytes, for ReaderName.\r
  @param[out]     State            Current state of the smart card reader.\r
  @param[out]     CardProtocol     Current protocol used to communicate with the smart card.\r
  @param[out]     Atr              A pointer to retrieve the ATR of the smart card.\r
  @param[in, out] AtrLength        On input, a pointer to hold the maximum size, in bytes,\r
                                   of Atr(usually 33).\r
                                   On output, the required size, inbytes, for the smart\r
                                   card ATR.\r
\r
  @retval EFI_SUCCESS            The requested command completed successfully.\r
  @retval EFI_INVALID_PARAMETER  This is NULL\r
  @retval EFI_INVALID_PARAMETER  ReaderName is not NULL but ReaderNameLength is NULL\r
  @retval EFI_INVALID_PARAMETER  Atr is not NULL but AtrLength is NULL\r
  @retval EFI_BUFFER_TOO_SMALL   ReaderNameLength is not big enough to hold the reader name.\r
                                 ReaderNameLength has been updated to the required value.\r
  @retval EFI_BUFFER_TOO_SMALL   AtrLength is not big enough to hold the ATR.\r
                                 AtrLength has been updated to the required value.\r
  @retval EFI_DEVICE_ERROR       Any other error condition, typically a reader removal.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SMART_CARD_READER_STATUS) (\r
  IN     EFI_SMART_CARD_READER_PROTOCOL    *This,\r
     OUT CHAR16                            *ReaderName OPTIONAL,\r
  IN OUT UINTN                             *ReaderNameLength OPTIONAL,\r
     OUT UINT32                            *State OPTIONAL,\r
     OUT UINT32                            *CardProtocol OPTIONAL,\r
     OUT UINT8                             *Atr OPTIONAL,\r
  IN OUT UINTN                             *AtrLength OPTIONAL\r
  );\r
\r
/**\r
  This function sends a command to the card or reader and returns its response.\r
\r
  The protocol to use to communicate with the smart card has been selected through\r
  SCardConnectcall.\r
\r
  In case RAPDULength indicates a buffer too small to holdthe response APDU, the\r
  function fails with EFI_BUFFER_TOO_SMALL.\r
\r
  @param[in]      This          A pointer to the EFI_USBFN_IO_PROTOCOLinstance.\r
  @param[in]      CAPDU         A pointer to a byte array thatcontains the Command\r
                                APDU to send to the smart card or reader.\r
  @param[in]      CAPDULength   Command APDU size, in bytes.\r
  @param[out]     RAPDU         A pointer to a byte array that will contain the\r
                                Response APDU.\r
  @param[in, out] RAPDULength   On input, the maximum size, inbytes, of the Response\r
                                APDU.\r
                                On output, the size, in bytes, of the Response APDU.\r
\r
  @retval EFI_SUCCESS           The requested command completed successfully.\r
  @retval EFI_INVALID_PARAMETER This is NULL.\r
  @retval EFI_INVALID_PARAMETER CAPDU is NULL or CAPDULength is 0.\r
  @retval EFI_BUFFER_TOO_SMALL  RAPDULength is not big enough to hold the response APDU.\r
                                RAPDULength has been updated to the required value.\r
  @retval EFI_NO_MEDIA          There is no card in the reader.\r
  @retval EFI_NOT_READY         Card is not powered.\r
  @retval EFI_PROTOCOL_ERROR    A protocol error has occurred.\r
  @retval EFI_TIMEOUT           The reader did not respond.\r
  @retval EFI_ACCESS_DENIED     A communication with the reader/card is already pending.\r
  @retval EFI_DEVICE_ERROR      Any other error condition, typically a reader removal.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SMART_CARD_READER_TRANSMIT) (\r
  IN     EFI_SMART_CARD_READER_PROTOCOL    *This,\r
  IN     UINT8                             *CAPDU,\r
  IN     UINTN                             CAPDULength,\r
     OUT UINT8                             *RAPDU,\r
  IN OUT UINTN                             *RAPDULength\r
  );\r
\r
/**\r
  This function provides direct access to the reader.\r
\r
  This function gives direct control to send commands to the driver or the reader.\r
  The ControlCode to use is vendor dependant; the only standard code defined is\r
  the one to get PC/SC part 10 features.\r
\r
  InBuffer and Outbuffer may be NULL when ControlCode operation does not require\r
  them.\r
\r
  @param[in]      This             Indicates a pointer to the calling context.\r
  @param[in]      ControlCode      The control code for the operation to perform.\r
  @param[in]      InBuffer         A pointer to the input parameters.\r
  @param[in]      InBufferLength   Size, in bytes, of input parameters.\r
  @param[out]     OutBuffer        A pointer to the output parameters.\r
  @param[in, out] OutBufferLength  On input, maximal size, in bytes, to store output\r
                                   parameters.\r
                                   On output, the size, in bytes, of output parameters.\r
\r
  @retval EFI_SUCCESS           The requested command completed successfully.\r
  @retval EFI_INVALID_PARAMETER This is NULL.\r
  @retval EFI_INVALID_PARAMETER ControlCode requires input parameters but:\r
                                  InBuffer is NULL or InBufferLenth is NULL or\r
                                  InBuffer is not NULL but InBufferLenth is less than\r
                                  expected.\r
  @retval EFI_INVALID_PARAMETER OutBuffer is not NULL but OutBufferLength is NULL.\r
  @retval EFI_UNSUPPORTED       ControlCode is not supported.\r
  @retval EFI_BUFFER_TOO_SMALL  OutBufferLength is not big enough to hold the output\r
                                parameters.\r
                                OutBufferLength has been updated to the required value.\r
  @retval EFI_NO_MEDIA          There is no card in the reader and the control code\r
                                specified requires one.\r
  @retval EFI_NOT_READY         ControlCode requires a powered card to operate.\r
  @retval EFI_PROTOCOL_ERROR    A protocol error has occurred.\r
  @retval EFI_TIMEOUT           The reader did not respond.\r
  @retval EFI_ACCESS_DENIED     A communication with the reader/card is already pending.\r
  @retval EFI_DEVICE_ERROR      Any other error condition, typically a reader removal.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SMART_CARD_READER_CONTROL) (\r
  IN     EFI_SMART_CARD_READER_PROTOCOL    *This,\r
  IN     UINT32                            ControlCode,\r
  IN     UINT8                             *InBuffer OPTIONAL,\r
  IN     UINTN                             InBufferLength OPTIONAL,\r
     OUT UINT8                             *OutBuffer OPTIONAL,\r
  IN OUT UINTN                             *OutBufferLength OPTIONAL\r
  );\r
\r
/**\r
  This function retrieves a reader or smart card attribute.\r
\r
  Possibly supported attrib values are listed in "PC/SC specification, Part 3:\r
  Requirements for PC-Connected Interface Devices".\r
\r
  @param[in]      This             Indicates a pointer to the calling context.\r
  @param[in]      Attrib           Identifier for the attribute to retrieve.\r
  @param[out]     OutBuffer        A pointer to a buffer that will contain\r
                                   attribute data.\r
  @param[in, out] OutBufferLength  On input, maximal size, in bytes, to store\r
                                   attribute data.\r
                                   On output, the size, in bytes, of attribute\r
                                   data.\r
\r
  @retval EFI_SUCCESS           The requested command completed successfully.\r
  @retval EFI_INVALID_PARAMETER This is NULL.\r
  @retval EFI_INVALID_PARAMETER OutBuffer is NULL or OutBufferLength is 0.\r
  @retval EFI_BUFFER_TOO_SMALL  OutBufferLength is not big enough to hold the output\r
                                parameters.\r
                                OutBufferLength has been updated to the required value.\r
  @retval EFI_UNSUPPORTED       Attribis not supported\r
  @retval EFI_NO_MEDIA          There is no card in the reader and Attrib value\r
                                requires one.\r
  @retval EFI_NOT_READY         Attrib requires a powered card to operate.\r
  @retval EFI_PROTOCOL_ERROR    A protocol error has occurred.\r
  @retval EFI_TIMEOUT           The reader did not respond.\r
  @retval EFI_DEVICE_ERROR      Any other error condition, typically a reader removal.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SMART_CARD_READER_GET_ATTRIB) (\r
  IN     EFI_SMART_CARD_READER_PROTOCOL    *This,\r
  IN     UINT32                            Attrib,\r
     OUT UINT8                             *OutBuffer,\r
  IN OUT UINTN                             *OutBufferLength\r
  );\r
\r
///\r
/// Smart card aware application invokes this protocol to get access to an inserted\r
/// smart card in the reader or to the reader itself.\r
///\r
struct _EFI_SMART_CARD_READER_PROTOCOL {\r
  EFI_SMART_CARD_READER_CONNECT        SCardConnect;\r
  EFI_SMART_CARD_READER_DISCONNECT     SCardDisconnect;\r
  EFI_SMART_CARD_READER_STATUS         SCardStatus;\r
  EFI_SMART_CARD_READER_TRANSMIT       SCardTransmit;\r
  EFI_SMART_CARD_READER_CONTROL        SCardControl;\r
  EFI_SMART_CARD_READER_GET_ATTRIB     SCardGetAttrib;\r
};\r
\r
extern EFI_GUID gEfiSmartCardReaderProtocolGuid;\r
\r
#endif\r
\r
Commit	Line	Data
21bd4958 FT	1	/** @file\r
	2	The UEFI Smart Card Reader Protocol provides an abstraction for device to provide\r
	3	smart card reader support. This protocol is very close to Part 5 of PC/SC workgroup\r
	4	specifications and provides an API to applications willing to communicate with a\r
	5	smart card or a smart card reader.\r
	6	\r
	7	Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>\r
9344f092	8	SPDX-License-Identifier: BSD-2-Clause-Patent\r
21bd4958 FT	9	\r
	10	**/\r
	11	\r
	12	#ifndef __SMART_CARD_READER_H__\r
	13	#define __SMART_CARD_READER_H__\r
	14	\r
	15	#define EFI_SMART_CARD_READER_PROTOCOL_GUID \\r
	16	{ \\r
	17	0x2a4d1adf, 0x21dc, 0x4b81, {0xa4, 0x2f, 0x8b, 0x8e, 0xe2, 0x38, 0x00, 0x60} \\r
	18	}\r
	19	\r
	20	typedef struct _EFI_SMART_CARD_READER_PROTOCOL EFI_SMART_CARD_READER_PROTOCOL;\r
	21	\r
	22	//\r
	23	// Codes for access mode\r
	24	//\r
	25	#define SCARD_AM_READER 0x0001 // Exclusive access to reader\r
	26	#define SCARD_AM_CARD 0x0002 // Exclusive access to card\r
	27	//\r
	28	// Codes for card action\r
	29	//\r
	30	#define SCARD_CA_NORESET 0x0000 // Don't reset card\r
	31	#define SCARD_CA_COLDRESET 0x0001 // Perform a cold reset\r
	32	#define SCARD_CA_WARMRESET 0x0002 // Perform a warm reset\r
	33	#define SCARD_CA_UNPOWER 0x0003 // Power off the card\r
	34	#define SCARD_CA_EJECT 0x0004 // Eject the card\r
	35	//\r
	36	// Protocol types\r
	37	//\r
	38	#define SCARD_PROTOCOL_UNDEFINED 0x0000\r
	39	#define SCARD_PROTOCOL_T0 0x0001\r
	40	#define SCARD_PROTOCOL_T1 0x0002\r
	41	#define SCARD_PROTOCOL_RAW 0x0004\r
	42	//\r
	43	// Codes for state type\r
	44	//\r
	45	#define SCARD_UNKNOWN 0x0000 /* state is unknown */\r
	46	#define SCARD_ABSENT 0x0001 /* Card is absent */\r
	47	#define SCARD_INACTIVE 0x0002 /* Card is present and not powered*/\r
	48	#define SCARD_ACTIVE 0x0003 /* Card is present and powered */\r
	49	//\r
	50	// Macro to generate a ControlCode & PC/SC part 10 control code\r
	51	//\r
	52	#define SCARD_CTL_CODE(code) (0x42000000 + (code))\r
	53	#define CM_IOCTL_GET_FEATURE_REQUEST SCARD_CTL_CODE(3400)\r
	54	\r
	55	/**\r
	56	This function requests connection to the smart card or the reader, using the\r
	57	appropriate reset type and protocol.\r
	58	\r
	59	The SCardConnectfunction requests access to the smart card or the reader. Upon\r
	60	success, it is then possible to call SCardTransmit.\r
	61	\r
	62	If AccessMode is set to SCARD_AM_READER, PreferredProtocols must be set to\r
	63	SCARD_PROTOCOL_UNDEFINED and CardAction to SCARD_CA_NORESET else function\r
	64	fails with EFI_INVALID_PARAMETER.\r
	65	\r
	66	@param[in] This Indicates a pointer to the calling context.\r
	67	@param[in] AccessMode Codes of access mode.\r
	68	@param[in] CardAction SCARD_CA_NORESET, SCARD_CA_COLDRESET or\r
	69	SCARD_CA_WARMRESET.\r
	70	@param[in] PreferredProtocols Bitmask of acceptable protocols.\r
	71	@param[out] ActiveProtocol A flag that indicates the active protocol.\r
	72	\r
73	@retval EFI_SUCCESS The requested command completed successfully.\r
74	@retval EFI_INVALID_PARAMETER This is NULL\r
75	@retval EFI_INVALID_PARAMETER AccessMode is not valid.\r
76	@retval EFI_INVALID_PARAMETER CardAction is not valid.\r
77	@retval EFI_INVALID_PARAMETER Invalid combination of AccessMode/CardAction/\r
78	PreferredProtocols.\r
79	@retval EFI_NOT_READY A smart card is inserted but failed to return an ATR.\r
80	@retval EFI_UNSUPPORTED PreferredProtocols does not contain an available\r
81	protocol to use.\r
82	@retval EFI_NO_MEDIA AccessMode is set to SCARD_AM_CARD but there is\r
83	no smart card inserted.\r
84	@retval EFI_ACCESS_DENIED Access is already locked by a previous SCardConnectcall.\r
85	@retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.\r
86	\r
87	**/\r
88	typedef\r
89	EFI_STATUS\r
90	(EFIAPI *EFI_SMART_CARD_READER_CONNECT) (\r
91	IN EFI_SMART_CARD_READER_PROTOCOL *This,\r
92	IN UINT32 AccessMode,\r
93	IN UINT32 CardAction,\r
94	IN UINT32 PreferredProtocols,\r
95	OUT UINT32 *ActiveProtocol\r
96	);\r
97	\r
98	/**\r
99	This function releases a connection previously taken by SCardConnect.\r
100	\r
101	The SCardDisconnect function releases the lock previously taken by SCardConnect.\r
102	In case the smart card has been removed before this call, thisfunction\r
103	returns EFI_SUCCESS. If there is no previous call to SCardConnect, this\r
104	function returns EFI_SUCCESS.\r
105	\r
106	@param[in] This Indicates a pointer to the calling context.\r
107	@param[in] CardAction Codes for card action.\r
108	\r
109	@retval EFI_SUCCESS The requested command completed successfully.\r
110	@retval EFI_INVALID_PARAMETER This is NULL\r
111	@retval EFI_INVALID_PARAMETER CardAction value is unknown.\r
112	@retval EFI_UNSUPPORTED Reader does not support Eject card feature\r
113	(disconnect was not performed).\r
114	@retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.\r
115	\r
116	**/\r
117	typedef\r
118	EFI_STATUS\r
119	(EFIAPI *EFI_SMART_CARD_READER_DISCONNECT) (\r
120	IN EFI_SMART_CARD_READER_PROTOCOL *This,\r
121	IN UINT32 CardAction\r
122	);\r
123	\r
124	/**\r
125	This function retrieves some basic information about the smart card and reader.\r
126	\r
127	The SCardStatusfunction retrieves basic reader and card information.\r
128	\r
129	If ReaderName, State, CardProtocolor Atris NULL, the function does not fail but\r
130	does not fill in such variables.\r
131	\r
132	If EFI_SUCCESS is not returned, ReaderName and Atr contents shall not be considered\r
133	as valid.\r
134	\r
135	@param[in] This Indicates a pointer to the calling context.\r
136	@param[out] ReaderName A pointer to a NULL terminated string that will\r
137	contain the reader name.\r
138	@param[in, out] ReaderNameLength On input, a pointer to the variablethat holds the\r
139	maximal size, in bytes,of ReaderName.\r
140	On output, the required size, in bytes, for ReaderName.\r
141	@param[out] State Current state of the smart card reader.\r
142	@param[out] CardProtocol Current protocol used to communicate with the smart card.\r
143	@param[out] Atr A pointer to retrieve the ATR of the smart card.\r
144	@param[in, out] AtrLength On input, a pointer to hold the maximum size, in bytes,\r
145	of Atr(usually 33).\r
146	On output, the required size, inbytes, for the smart\r
147	card ATR.\r
148	\r
149	@retval EFI_SUCCESS The requested command completed successfully.\r
150	@retval EFI_INVALID_PARAMETER This is NULL\r
151	@retval EFI_INVALID_PARAMETER ReaderName is not NULL but ReaderNameLength is NULL\r
152	@retval EFI_INVALID_PARAMETER Atr is not NULL but AtrLength is NULL\r
153	@retval EFI_BUFFER_TOO_SMALL ReaderNameLength is not big enough to hold the reader name.\r
154	ReaderNameLength has been updated to the required value.\r
155	@retval EFI_BUFFER_TOO_SMALL AtrLength is not big enough to hold the ATR.\r
156	AtrLength has been updated to the required value.\r
157	@retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.\r
158	\r
159	**/\r
160	typedef\r
161	EFI_STATUS\r
162	(EFIAPI *EFI_SMART_CARD_READER_STATUS) (\r
163	IN EFI_SMART_CARD_READER_PROTOCOL *This,\r
164	OUT CHAR16 *ReaderName OPTIONAL,\r
165	IN OUT UINTN *ReaderNameLength OPTIONAL,\r
166	OUT UINT32 *State OPTIONAL,\r
167	OUT UINT32 *CardProtocol OPTIONAL,\r
168	OUT UINT8 *Atr OPTIONAL,\r
169	IN OUT UINTN *AtrLength OPTIONAL\r
170	);\r
171	\r
172	/**\r
173	This function sends a command to the card or reader and returns its response.\r
174	\r
175	The protocol to use to communicate with the smart card has been selected through\r
176	SCardConnectcall.\r
177	\r
178	In case RAPDULength indicates a buffer too small to holdthe response APDU, the\r
179	function fails with EFI_BUFFER_TOO_SMALL.\r
180	\r
181	@param[in] This A pointer to the EFI_USBFN_IO_PROTOCOLinstance.\r
182	@param[in] CAPDU A pointer to a byte array thatcontains the Command\r
183	APDU to send to the smart card or reader.\r
184	@param[in] CAPDULength Command APDU size, in bytes.\r
185	@param[out] RAPDU A pointer to a byte array that will contain the\r
186	Response APDU.\r
187	@param[in, out] RAPDULength On input, the maximum size, inbytes, of the Response\r
188	APDU.\r
189	On output, the size, in bytes, of the Response APDU.\r
190	\r
191	@retval EFI_SUCCESS The requested command completed successfully.\r
192	@retval EFI_INVALID_PARAMETER This is NULL.\r
193	@retval EFI_INVALID_PARAMETER CAPDU is NULL or CAPDULength is 0.\r
194	@retval EFI_BUFFER_TOO_SMALL RAPDULength is not big enough to hold the response APDU.\r
195	RAPDULength has been updated to the required value.\r
196	@retval EFI_NO_MEDIA There is no card in the reader.\r
197	@retval EFI_NOT_READY Card is not powered.\r
198	@retval EFI_PROTOCOL_ERROR A protocol error has occurred.\r
199	@retval EFI_TIMEOUT The reader did not respond.\r
200	@retval EFI_ACCESS_DENIED A communication with the reader/card is already pending.\r
201	@retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.\r
202	\r
203	**/\r
204	typedef\r
205	EFI_STATUS\r
206	(EFIAPI *EFI_SMART_CARD_READER_TRANSMIT) (\r
207	IN EFI_SMART_CARD_READER_PROTOCOL *This,\r
208	IN UINT8 *CAPDU,\r
209	IN UINTN CAPDULength,\r
210	OUT UINT8 *RAPDU,\r
211	IN OUT UINTN *RAPDULength\r
21bd4958 FT	212	);\r
	213	\r
	214	/**\r
	215	This function provides direct access to the reader.\r
	216	\r
	217	This function gives direct control to send commands to the driver or the reader.\r
	218	The ControlCode to use is vendor dependant; the only standard code defined is\r
	219	the one to get PC/SC part 10 features.\r
	220	\r
	221	InBuffer and Outbuffer may be NULL when ControlCode operation does not require\r
	222	them.\r
	223	\r
	224	@param[in] This Indicates a pointer to the calling context.\r
	225	@param[in] ControlCode The control code for the operation to perform.\r
	226	@param[in] InBuffer A pointer to the input parameters.\r
	227	@param[in] InBufferLength Size, in bytes, of input parameters.\r
	228	@param[out] OutBuffer A pointer to the output parameters.\r
	229	@param[in, out] OutBufferLength On input, maximal size, in bytes, to store output\r
	230	parameters.\r
	231	On output, the size, in bytes, of output parameters.\r
	232	\r
	233	@retval EFI_SUCCESS The requested command completed successfully.\r
	234	@retval EFI_INVALID_PARAMETER This is NULL.\r
	235	@retval EFI_INVALID_PARAMETER ControlCode requires input parameters but:\r
	236	InBuffer is NULL or InBufferLenth is NULL or\r
	237	InBuffer is not NULL but InBufferLenth is less than\r
	238	expected.\r
	239	@retval EFI_INVALID_PARAMETER OutBuffer is not NULL but OutBufferLength is NULL.\r
	240	@retval EFI_UNSUPPORTED ControlCode is not supported.\r
	241	@retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output\r
	242	parameters.\r
	243	OutBufferLength has been updated to the required value.\r
	244	@retval EFI_NO_MEDIA There is no card in the reader and the control code\r
	245	specified requires one.\r
	246	@retval EFI_NOT_READY ControlCode requires a powered card to operate.\r
	247	@retval EFI_PROTOCOL_ERROR A protocol error has occurred.\r
	248	@retval EFI_TIMEOUT The reader did not respond.\r
	249	@retval EFI_ACCESS_DENIED A communication with the reader/card is already pending.\r
	250	@retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.\r
	251	\r
	252	**/\r
	253	typedef\r
	254	EFI_STATUS\r
	255	(EFIAPI *EFI_SMART_CARD_READER_CONTROL) (\r
	256	IN EFI_SMART_CARD_READER_PROTOCOL *This,\r
	257	IN UINT32 ControlCode,\r
	258	IN UINT8 *InBuffer OPTIONAL,\r
	259	IN UINTN InBufferLength OPTIONAL,\r
	260	OUT UINT8 *OutBuffer OPTIONAL,\r
	261	IN OUT UINTN *OutBufferLength OPTIONAL\r
	262	);\r
	263	\r
	264	/**\r
	265	This function retrieves a reader or smart card attribute.\r
	266	\r
	267	Possibly supported attrib values are listed in "PC/SC specification, Part 3:\r
	268	Requirements for PC-Connected Interface Devices".\r
	269	\r
	270	@param[in] This Indicates a pointer to the calling context.\r
	271	@param[in] Attrib Identifier for the attribute to retrieve.\r
	272	@param[out] OutBuffer A pointer to a buffer that will contain\r
	273	attribute data.\r
	274	@param[in, out] OutBufferLength On input, maximal size, in bytes, to store\r
	275	attribute data.\r
276	On output, the size, in bytes, of attribute\r
277	data.\r
278	\r
279	@retval EFI_SUCCESS The requested command completed successfully.\r
280	@retval EFI_INVALID_PARAMETER This is NULL.\r
281	@retval EFI_INVALID_PARAMETER OutBuffer is NULL or OutBufferLength is 0.\r
282	@retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output\r
283	parameters.\r
284	OutBufferLength has been updated to the required value.\r
285	@retval EFI_UNSUPPORTED Attribis not supported\r
286	@retval EFI_NO_MEDIA There is no card in the reader and Attrib value\r
287	requires one.\r
288	@retval EFI_NOT_READY Attrib requires a powered card to operate.\r
289	@retval EFI_PROTOCOL_ERROR A protocol error has occurred.\r
290	@retval EFI_TIMEOUT The reader did not respond.\r
291	@retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.\r
292	\r
293	**/\r
294	typedef\r
295	EFI_STATUS\r
296	(EFIAPI *EFI_SMART_CARD_READER_GET_ATTRIB) (\r
297	IN EFI_SMART_CARD_READER_PROTOCOL *This,\r
298	IN UINT32 Attrib,\r
299	OUT UINT8 *OutBuffer,\r
300	IN OUT UINTN *OutBufferLength\r
301	);\r
302	\r
303	///\r
304	/// Smart card aware application invokes this protocol to get access to an inserted\r
305	/// smart card in the reader or to the reader itself.\r
306	///\r
307	struct _EFI_SMART_CARD_READER_PROTOCOL {\r
308	EFI_SMART_CARD_READER_CONNECT SCardConnect;\r
309	EFI_SMART_CARD_READER_DISCONNECT SCardDisconnect;\r
310	EFI_SMART_CARD_READER_STATUS SCardStatus;\r
311	EFI_SMART_CARD_READER_TRANSMIT SCardTransmit;\r
312	EFI_SMART_CARD_READER_CONTROL SCardControl;\r
313	EFI_SMART_CARD_READER_GET_ATTRIB SCardGetAttrib;\r
314	};\r
315	\r
316	extern EFI_GUID gEfiSmartCardReaderProtocolGuid;\r
317	\r
318	#endif\r
319	\r