SCardStatus

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.

LONG SCardStatus(
  IN SCARDHANDLE hCard,
  OUT LPTSTR  mszReaderNames,
  IN OUT LPDWORD pcchReaderLen,
  OUT LPDWORD pdwState,
  OUT LPDWORD pdwProtocol,
  OUT LPBYTE pbAtr,
  OUT LPDWORD pbcAtrLen
);

Parameters

hCard
This is the reference value returned from SCardConnect.
mszReaderNames
Receives a list of friendly names (multi-string) by which the currently connected reader is known.
pcchReaderLen
On input, supplies the length of the mszReaderNames buffer

On output, receives the actual length (in characters) of the reader name list, including the trailing NULL character.

pdwState
Receives the 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_NEGOTIABLEMODE The card has been reset and is awaiting PTS negotiation.
SCARD_SPECIFICMODE The card has been reset and specific communication protocols have been established.

pdwProtocol
Receives the current protocol, if any. The returned value is meaningful only if the returned value of pdwState is SCARD_SPECIFICMODE. Possible returned values are the following:
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
Points to a 32-byte buffer that receives the ATR string from the currently inserted card, if available.
pbcAtrLen
Points to a DWORD to receive the number of bytes in the ATR string (32 bytes maximum).

Return Values

If the function… The return value is…
Succeeds SCARD_S_SUCCESS.
Fails An error code (see Error Codes for a list of all error codes).

Remarks

SCardStatus is a smart card and reader access function. For a description of other access functions, see Smart Card and Reader Access Functions.

QuickInfo

  Windows NT: Use version 4.0 SP3 and later.
  Windows: Use Windows 95 OSR2.1.
  Windows CE: Unsupported.
  Header: Declared in winscard.h.
  Import Library: Link with winscard.lib.

See Also

SCardConnect, SCardDisconnect