Share via

SCardStatus

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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.

Syntax

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

Parameters

  • hCard
    [in] Handle to the reference value returned from SCardConnect.
  • szReaderName
    [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 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, szReaderName is converted to a byte pointer, and it receives the address of a block of memory that contains the multiple-string structure.

  • 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 card reader.

    SCARD_PRESENT

    A card is present in the card reader, but it is not in position for use

    SCARD_SWALLOWED

    A card is in the reader and is in position for use. The card is not powered.

    SCARD_POWERED

    The card is powered but the reader cannot determine its mode.

    SCARD_NEGOTIABLE

    The card has been reset and is waiting for protocol negotiation.

    SCARD_SPECIFIC

    The card has been reset and a protocol has been negotiated.

  • 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 Value

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

Header winscard.h
Library winscard.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

SCardConnect
SCardDisconnect