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

Parameters

  • hCard
    Handle to 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, 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
    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
    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
    Pointer to a 32-byte buffer that receives the ATR string from the currently inserted card, if available.

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

Return Values

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

Remarks

SCardStatus is a smart card and reader access function.

Requirements

Runs on Versions Defined in Include Link to
Windows CE OS 3.0 and later Winscard.h   Winscard.lib

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

SCardConnect, SCardDisconnect

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.