SCardStatusA function (winscard.h)

Article
02/09/2023

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 SCardStatusA(
  [in]                SCARDHANDLE hCard,
  [out]               LPSTR       mszReaderNames,
  [in, out, optional] LPDWORD     pcchReaderLen,
  [out, optional]     LPDWORD     pdwState,
  [out, optional]     LPDWORD     pdwProtocol,
  [out]               LPBYTE      pbAtr,
  [in, out, optional] LPDWORD     pcbAtrLen
);

Parameters

[in] hCard

Reference value returned from SCardConnect.

[out] mszReaderNames

List of display names (multiple string) by which the currently connected reader is known.

[in, out, optional] pcchReaderLen

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.

[out, optional] pdwState

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.

[out, optional] pdwProtocol

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.

[out] pbAtr

Pointer to a 32-byte buffer that receives the ATR string from the currently inserted card, if available.

[in, out, optional] pcbAtrLen

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;
}

Note

The winscard.h header defines SCardStatus as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	winscard.h
Library	Winscard.lib
DLL	Winscard.dll

Share via