SCardStatus function
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 WINAPI SCardStatus( _In_ SCARDHANDLE hCard, _Out_ LPTSTR szReaderName, _Inout_opt_ LPDWORD pcchReaderLen, _Out_opt_ LPDWORD pdwState, _Out_opt_ LPDWORD pdwProtocol, _Out_ LPBYTE pbAtr, _Inout_opt_ LPDWORD pcbAtrLen );
Parameters
- hCard [in]
-
Reference value returned from SCardConnect.
- szReaderName [out]
-
List of display names (multiple string) by which the currently connected reader is known.
- pcchReaderLen [in, out, optional]
-
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.
- pdwState [out, optional]
-
Current state of the smart card in the reader. Upon success, it receives one of the following state indicators.
Value Meaning - SCARD_ABSENT
There is no card in the reader.
- SCARD_PRESENT
There is a card in the reader, but it has not been moved into position for use.
- SCARD_SWALLOWED
There is a card in the reader in position for use. The card is not powered.
- SCARD_POWERED
Power is being provided to the card, but the reader driver is unaware of the mode of the card.
- SCARD_NEGOTIABLE
The card has been reset and is awaiting PTS negotiation.
- SCARD_SPECIFIC
The card has been reset and specific communication protocols have been established.
- pdwProtocol [out, optional]
-
Current protocol, if any. The returned value is meaningful only if the returned value of pdwState is SCARD_SPECIFICMODE.
Value Meaning - SCARD_PROTOCOL_RAW
The Raw Transfer protocol is in use.
- SCARD_PROTOCOL_T0
The ISO 7816/3 T=0 protocol is in use.
- SCARD_PROTOCOL_T1
The ISO 7816/3 T=1 protocol is in use.
- pbAtr [out]
-
Pointer to a 32-byte buffer that receives the ATR string from the currently inserted card, if available.
- pcbAtrLen [in, out, optional]
-
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; }
Requirements
|
Minimum supported client |
Windows XP [desktop apps only] |
|---|---|
|
Minimum supported server |
Windows Server 2003 [desktop apps only] |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names |
SCardStatusW (Unicode) and SCardStatusA (ANSI) |
See also