SCardGetStatusChange

Synopsis:

#include <winscard.h>

LONG SCardGetStatusChange(SCARDCONTEXT hContext,
    DWORD dwTimeout,
    LPSCARD_READERSTATE rgReaderStates,
    DWORD cReaders);

Parameters:

hContext	IN	Connection context to the PC/SC Resource Manager
dwTimeout	IN	Maximum waiting time (in miliseconds) for status change, zero (or INFINITE) for infinite
rgReaderStates	INOUT	Structures of readers with current states
cReaders	IN	Number of structures

Description:

This function receives a structure or list of structures containing reader names. It then blocks for a change in state to occur on any of the OR'd values contained in dwCurrentState for a maximum blocking time of dwTimeout or forever if INFINITE is used. The new event state will be contained in dwEventState. A status change might be a card insertion or removal event, a change in ATR, etc.

This function will block for reader availability if cReaders is equal to zero and rgReaderStates is NULL.

typedef struct {
    LPCSTR szReader;     /* Reader name                       */
    LPVOID pvUserData;    /* User defined data                 */
    DWORD dwCurrentState; /* Current state of reader           */
    DWORD dwEventState;   /* Reader state after a state change */
    DWORD cbAtr;          /* ATR Length, usually MAX_ATR_SIZE  */
    BYTE rgbAtr[MAX_ATR_SIZE]; /* ATR Value                    */
} SCARD_READERSTATE;

typedef SCARD_READERSTATE *PSCARD_READERSTATE, **LPSCARD_READERSTATE;

Value of dwCurrentState and dwEventState	Meaning
SCARD_STATE_UNAWARE	The application is unaware of the current state, and would like to know. The use of this value results in an immediate return from state transition monitoring services. This is represented by all bits set to zero
SCARD_STATE_IGNORE	This reader should be ignored
SCARD_STATE_CHANGED	There is a difference between the state believed by the application, and the state known by the resource manager. When this bit is set, the application may assume a significant state change has occurred on this reader
SCARD_STATE_UNKNOWN	The given reader name is not recognized by the resource manager. If this bit is set, then SCARD_STATE_CHANGED and SCARD_STATE_IGNORE will also be set

Value of dwCurrentState and dwEventState	Meaning
SCARD_STATE_UNAVAILABLE	The actual state of this reader is not available. If this bit is set, then all the following bits are clear
SCARD_STATE_EMPTY	There is no card in the reader. If this bit is set, all the following bits will be clear
SCARD_STATE_PRESENT	There is a card in the reader
SCARD_STATE_ATRMATCH	There is a card in the reader with an ATR matching one of the target cards. If this bit is set, SCARD_STATE_PRESENT will also be set. This bit is only returned on the SCardLocateCards function
SCARD_STATE_EXCLUSIVE	The card in the reader is allocated for exclusive use by another application. If this bit is set, SCARD_STATE_PRESENT will also be set
SCARD_STATE_INUSE	The card in the reader is in use by one or more other applications, but may be connected to in shared mode. If this bit is set, SCARD_STATE_PRESENT will also be set
SCARD_STATE_MUTE	There is an unresponsive card in the reader

Example:

SCARDCONTEXT hContext;
SCARD_READERSTATE_A rgReaderStates[1];
LONG rv;

rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);

rgReaderStates[0].szReader = "Reader X";
rgReaderStates[0].dwCurrentState = SCARD_STATE_UNAWARE;

rv = SCardGetStatusChange(hContext, INFINITE, rgReaderStates, 1);
printf("reader state: 0x%04X\n", rgReaderStates[0].dwEventState);

Returns:

SCARD_S_SUCCESS	Successful
SCARD_E_INVALID_VALUE	Invalid States, reader name, etc
SCARD_E_INVALID_HANDLE	Invalid hContext handle
SCARD_E_READER_UNAVAILABLE	The reader is unavailable