Share via

SCardStatus

  • Article

This 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(
  SCARDHANDLE hCard, 
  LPTSTR mszReaderNames, 
  LPDWORD pcchReaderLen, 
  LPDWORD pdwState, 
  LPDWORD pdwProtocol, 
  LPBYTE pbAtr, 
  LPDWORD pbcAtrLen 
);

Parameters

  • hCard
    [in] Handle to the reference value returned from SCardConnect.

  • mszReaderNames
    [out] Receives a list of friendly names (multi-string) by which the currently connected reader is known.

  • pcchReaderLen
    [in, out] On input, pointer to the length of the mszReaderNames buffer.

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

  • pdwState
    [out] Pointer that specifies the current state of the smart card in the reader. The following table shows state indicators, one of which pdwState receives upon success.

    Value Description
    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
    [out] Pointer that specifies the current protocol, if any. The returned value is meaningful only if the returned value of pdwState is SCARD_SPECIFICMODE. The following table shows the possible return values for pdwProtocol.

    Value Description
    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.

  • pbcAtrLen
    [out] Pointer to a DWORD to receive the number of bytes in the ATR string (32 bytes maximum).

Return Values

The following table shows the possible return values.

Value Description
SCARD_S_SUCCESS Succeeds
An error value (see Smart Card Error Values for a list of all error values). Fails

Remarks

SCardStatus is a smart card and reader access function.

Requirements

OS Versions: Windows CE 3.0 and later.
Header: Winscard.h.
Link Library: Winscard.lib.

See Also

SCardConnect | SCardDisconnect

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.