SCardStatusA function (winscard.h)
The SCardStatus function provides the current status of a smart card in a reader. You can call it any time after a successful call to SCardConnect and before a successful call to SCardDisconnect. It does not affect the state of the reader or reader driver.
Syntax
LONG SCardStatusA(
[in] SCARDHANDLE hCard,
[out] LPSTR mszReaderNames,
[in, out, optional] LPDWORD pcchReaderLen,
[out, optional] LPDWORD pdwState,
[out, optional] LPDWORD pdwProtocol,
[out] LPBYTE pbAtr,
[in, out, optional] LPDWORD pcbAtrLen
);
Parameters
[in] hCard
Reference value returned from SCardConnect.
[out] mszReaderNames
List of display names (multiple string) by which the currently connected reader is known.
[in, out, optional] pcchReaderLen
On input, supplies the length of the szReaderName buffer.
On output, receives the actual length (in characters) of the reader name list, including the trailing NULL character. If this buffer length is specified as SCARD_AUTOALLOCATE, then szReaderName is converted to a pointer to a byte pointer, and it receives the address of a block of memory that contains the multiple-string structure.
[out, optional] pdwState
Current state of the smart card in the reader. Upon success, it receives one of the following state indicators.
Value | Meaning |
---|---|
|
There is no card in the reader. |
|
There is a card in the reader, but it has not been moved into position for use. |
|
There is a card in the reader in position for use. The card is not powered. |
|
Power is being provided to the card, but the reader driver is unaware of the mode of the card. |
|
The card has been reset and is awaiting PTS negotiation. |
|
The card has been reset and specific communication protocols have been established. |
[out, optional] pdwProtocol
Current protocol, if any. The returned value is meaningful only if the returned value of pdwState is SCARD_SPECIFICMODE.
Value | Meaning |
---|---|
|
The Raw Transfer protocol is in use. |
|
The ISO 7816/3 T=0 protocol is in use. |
|
The ISO 7816/3 T=1 protocol is in use. |
[out] pbAtr
Pointer to a 32-byte buffer that receives the ATR string from the currently inserted card, if available.
[in, out, optional] pcbAtrLen
On input, supplies the length of the pbAtr buffer. On output, receives the number of bytes in the ATR string (32 bytes maximum). If this buffer length is specified as SCARD_AUTOALLOCATE, then pbAtr is converted to a pointer to a byte pointer, and it receives the address of a block of memory that contains the multiple-string structure.
Return value
If the function successfully provides the current status of a smart card in a reader, the return value is SCARD_S_SUCCESS.
If the function fails, it returns an error code. For more information, see Smart Card Return Values.
Remarks
The SCardStatus function is a smart card and reader access function. For information about other access functions, see Smart Card and Reader Access Functions.
Examples
The following example shows how to determine the state of the smart card.
WCHAR szReader[200];
DWORD cch = 200;
BYTE bAttr[32];
DWORD cByte = 32;
DWORD dwState, dwProtocol;
LONG lReturn;
// Determine the status.
// hCardHandle was set by an earlier call to SCardConnect.
lReturn = SCardStatus(hCardHandle,
szReader,
&cch,
&dwState,
&dwProtocol,
(LPBYTE)&bAttr,
&cByte);
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardStatus\n");
exit(1); // or other appropriate action
}
// Examine retrieved status elements.
// Look at the reader name and card state.
printf("%S\n", szReader );
switch ( dwState )
{
case SCARD_ABSENT:
printf("Card absent.\n");
break;
case SCARD_PRESENT:
printf("Card present.\n");
break;
case SCARD_SWALLOWED:
printf("Card swallowed.\n");
break;
case SCARD_POWERED:
printf("Card has power.\n");
break;
case SCARD_NEGOTIABLE:
printf("Card reset and waiting PTS negotiation.\n");
break;
case SCARD_SPECIFIC:
printf("Card has specific communication protocols set.\n");
break;
default:
printf("Unknown or unexpected card state.\n");
break;
}
Note
The winscard.h header defines SCardStatus as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows XP [desktop apps only] |
Minimum supported server | Windows Server 2003 [desktop apps only] |
Target Platform | Windows |
Header | winscard.h |
Library | Winscard.lib |
DLL | Winscard.dll |