Logo Search packages:      
Sourcecode: pcsc-lite version File versions

LONG SCardGetStatusChange ( SCARDCONTEXT  hContext,
DWORD  dwTimeout,
LPSCARD_READERSTATE_A  rgReaderStates,
DWORD  cReaders 
)

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.

To wait for a reader event (reader added or removed) you may use the special reader name "\\?PnP?\Notification". If a reader event occurs the state of this reader will change and the bit SCARD_STATE_CHANGED will be set.

 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:

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

Parameters:
[in] hContext Connection context to the PC/SC Resource Manager.
[in] dwTimeout Maximum waiting time (in miliseconds) for status change, zero (or INFINITE) for infinite.
rgReaderStates [inout] Structures of readers with current states.
[in] cReaders Number of structures.
Returns:
Error code.
Return values:
SCARD_S_SUCCESS Successful (SCARD_S_SUCCESS)
SCARD_E_NO_SERVICE Server is not running (SCARD_E_NO_SERVICE)
SCARD_E_INVALID_PARAMETER rgReaderStates is NULL and cReaders > 0 (SCARD_E_INVALID_PARAMETER)
SCARD_E_INVALID_VALUE Invalid States, reader name, etc (SCARD_E_INVALID_VALUE)
SCARD_E_INVALID_HANDLE Invalid hContext handle (SCARD_E_INVALID_HANDLE)
SCARD_E_READER_UNAVAILABLE The reader is unavailable (SCARD_E_READER_UNAVAILABLE)
SCARD_E_TIMEOUT The user-specified timeout value has expired (SCARD_E_TIMEOUT)
 SCARDCONTEXT hContext;
 SCARD_READERSTATE_A rgReaderStates[2];
 LONG rv;
 ...
 rv = SCardEstablishContext(SCARD_SCOPE_SYSTEM, NULL, NULL, &hContext);
 ...
 rgReaderStates[0].szReader = "Reader X";
 rgReaderStates[0].dwCurrentState = SCARD_STATE_UNAWARE;

 rgReaderStates[1].szReader = "\\\\?PnP?\\Notification";
 rgReaderStates[1].dwCurrentState = SCARD_STATE_UNAWARE;
 ...
 rv = SCardGetStatusChange(hContext, INFINITE, rgReaderStates, 2);
 printf("reader state: 0x%04X\n", rgReaderStates[0].dwEventState);
 printf("reader state: 0x%04X\n", rgReaderStates[1].dwEventState);

Definition at line 1852 of file winscard_clnt.c.

References BLOCK_STATUS_BLOCKING, BLOCK_STATUS_RESUME, pubReaderStatesList::cardAtr, pubReaderStatesList::cardAtrLength, _psContextMap::contextBlockStatus, INFINITE, PCSCLITE_MAX_READERS_CONTEXTS, PCSCLITE_STATUS_POLL_RATE, psContextMap, pubReaderStatesList::readerSharing, pubReaderStatesList::readerState, SCARD_ABSENT, SCARD_E_CANCELLED, SCARD_E_INVALID_HANDLE, SCARD_E_INVALID_PARAMETER, SCARD_E_INVALID_VALUE, SCARD_E_READER_UNAVAILABLE, SCARD_E_TIMEOUT, SCARD_PRESENT, SCARD_S_SUCCESS, SCARD_STATE_ATRMATCH, SCARD_STATE_CHANGED, SCARD_STATE_EMPTY, SCARD_STATE_EXCLUSIVE, SCARD_STATE_IGNORE, SCARD_STATE_INUSE, SCARD_STATE_MUTE, SCARD_STATE_PRESENT, SCARD_STATE_UNAVAILABLE, SCARD_STATE_UNAWARE, SCARD_STATE_UNKNOWN, SCARD_SWALLOWED, SCARD_UNKNOWN, SCardCheckDaemonAvailability(), SCardGetContextIndice(), and SYS_USleep().

{
      PSCARD_READERSTATE_A currReader;
      PREADER_STATE rContext;
      long dwTime = dwTimeout;
      DWORD dwState;
      DWORD dwBreakFlag = 0;
      int j;
      LONG dwContextIndex;
      int currentReaderCount = 0;
      LONG rv = SCARD_S_SUCCESS;

      PROFILE_START

      if ((rgReaderStates == NULL && cReaders > 0)
            || (cReaders > PCSCLITE_MAX_READERS_CONTEXTS))
            return SCARD_E_INVALID_PARAMETER;

      /* Check the integrity of the reader states structures */
      for (j = 0; j < cReaders; j++)
      {
            if (rgReaderStates[j].szReader == NULL)
                  return SCARD_E_INVALID_VALUE;
      }

      /* return if all readers are SCARD_STATE_IGNORE */
      if (cReaders > 0)
      {
            int nbNonIgnoredReaders = cReaders;

            for (j=0; j<cReaders; j++)
                  if (rgReaderStates[j].dwCurrentState & SCARD_STATE_IGNORE)
                        nbNonIgnoredReaders--;

            if (0 == nbNonIgnoredReaders)
                  return SCARD_S_SUCCESS;
      }

      rv = SCardCheckDaemonAvailability();
      if (rv != SCARD_S_SUCCESS)
            return rv;

      /*
       * Make sure this context has been opened
       */
      dwContextIndex = SCardGetContextIndice(hContext);
      if (dwContextIndex == -1)
            return SCARD_E_INVALID_HANDLE;

      (void)SYS_MutexLock(psContextMap[dwContextIndex].mMutex);

      /* check the context is still opened */
      dwContextIndex = SCardGetContextIndice(hContext);
      if (dwContextIndex == -1)
            /* the context is now invalid
             * -> another thread may have called SCardReleaseContext
             * -> so the mMutex has been unlocked */
            return SCARD_E_INVALID_HANDLE;

      /*
       * Application is waiting for a reader - return the first available
       * reader
       * This is DEPRECATED. Use the special reader name \\?PnP?\Notification
       * instead
       */
      if (cReaders == 0)
      {
            while (1)
            {
                  int i;

                  rv = SCardCheckDaemonAvailability();
                  if (rv != SCARD_S_SUCCESS)
                        goto end;

                  for (i = 0; i < PCSCLITE_MAX_READERS_CONTEXTS; i++)
                  {
                        if ((readerStates[i])->readerID != 0)
                        {
                              /* Reader was found */
                              rv = SCARD_S_SUCCESS;
                              goto end;
                        }
                  }

                  if (dwTimeout == 0)
                  {
                        /* return immediately - no reader available */
                        rv = SCARD_E_READER_UNAVAILABLE;
                        goto end;
                  }

                  dwTime = WaitForPcscdEvent(hContext, dwTime);
                  if (dwTimeout != INFINITE)
                  {
                        if (dwTime <= 0)
                        {
                              rv = SCARD_E_TIMEOUT;
                              goto end;
                        }
                  }
            }
      }

      /*
       * End of search for readers
       */

      /* Clear the event state for all readers */
      for (j = 0; j < cReaders; j++)
            rgReaderStates[j].dwEventState = 0;

      /* Now is where we start our event checking loop */
      Log1(PCSC_LOG_DEBUG, "Event Loop Start");

      psContextMap[dwContextIndex].contextBlockStatus = BLOCK_STATUS_BLOCKING;

      /* Get the initial reader count on the system */
      for (j=0; j < PCSCLITE_MAX_READERS_CONTEXTS; j++)
            if ((readerStates[j])->readerID != 0)
                  currentReaderCount++;

      j = 0;
      do
      {
            rv = SCardCheckDaemonAvailability();
            if (rv != SCARD_S_SUCCESS)
            {
                  if (psContextMap[dwContextIndex].mMutex)
                        (void)SYS_MutexUnLock(psContextMap[dwContextIndex].mMutex);

                  PROFILE_END(rv)

                  return rv;
            }

            currReader = &rgReaderStates[j];

            /* Ignore for IGNORED readers */
            if (!(currReader->dwCurrentState & SCARD_STATE_IGNORE))
            {
                  LPSTR lpcReaderName;
                  int i;

        /************ Looks for correct readernames *********************/

                  lpcReaderName = (char *) currReader->szReader;

                  for (i = 0; i < PCSCLITE_MAX_READERS_CONTEXTS; i++)
                  {
                        if (strcmp(lpcReaderName, (readerStates[i])->readerName) == 0)
                              break;
                  }

                  /* The requested reader name is not recognized */
                  if (i == PCSCLITE_MAX_READERS_CONTEXTS)
                  {
                        /* PnP special reader? */
                        if (strcasecmp(lpcReaderName, "\\\\?PnP?\\Notification") == 0)
                        {
                              int k, newReaderCount = 0;

                              for (k=0; k < PCSCLITE_MAX_READERS_CONTEXTS; k++)
                                    if ((readerStates[k])->readerID != 0)
                                          newReaderCount++;

                              if (newReaderCount != currentReaderCount)
                              {
                                    Log1(PCSC_LOG_INFO, "Reader list changed");
                                    currentReaderCount = newReaderCount;

                                    currReader->dwEventState |= SCARD_STATE_CHANGED;
                                    dwBreakFlag = 1;
                              }
                        }
                        else
                        {
                              currReader->dwEventState = SCARD_STATE_UNKNOWN | SCARD_STATE_UNAVAILABLE;
                              if (!(currReader->dwCurrentState & SCARD_STATE_UNKNOWN))
                              {
                                    currReader->dwEventState |= SCARD_STATE_CHANGED;
                                    /*
                                     * Spec says use SCARD_STATE_IGNORE but a removed USB
                                     * reader with eventState fed into currentState will
                                     * be ignored forever
                                     */
                                    dwBreakFlag = 1;
                              }
                        }
                  }
                  else
                  {
                        /* The reader has come back after being away */
                        if (currReader->dwCurrentState & SCARD_STATE_UNKNOWN)
                        {
                              currReader->dwEventState |= SCARD_STATE_CHANGED;
                              currReader->dwEventState &= ~SCARD_STATE_UNKNOWN;
                              dwBreakFlag = 1;
                        }

      /*****************************************************************/

                        /* Set the reader status structure */
                        rContext = readerStates[i];

                        /* Now we check all the Reader States */
                        dwState = rContext->readerState;
                        {
                              int currentCounter, stateCounter;

                              stateCounter = (dwState >> 16) & 0xFFFF;
                              currentCounter = (currReader->dwCurrentState >> 16) & 0xFFFF;

                              /* has the event counter changed since the last call? */
                              if (stateCounter != currentCounter)
                              {
                                    currReader->dwEventState |= SCARD_STATE_CHANGED;
                                    dwBreakFlag = 1;
                              }

                              /* add an event counter in the upper word of dwEventState */
                              currReader->dwEventState =
                                    ((currReader->dwEventState & 0xffff )
                                    | (stateCounter << 16));
                        }

      /*********** Check if the reader is in the correct state ********/
                        if (dwState & SCARD_UNKNOWN)
                        {
                              /* reader is in bad state */
                              currReader->dwEventState = SCARD_STATE_UNAVAILABLE;
                              if (!(currReader->dwCurrentState & SCARD_STATE_UNAVAILABLE))
                              {
                                    /* App thinks reader is in good state and it is not */
                                    currReader->dwEventState |= SCARD_STATE_CHANGED;
                                    dwBreakFlag = 1;
                              }
                        }
                        else
                        {
                              /* App thinks reader in bad state but it is not */
                              if (currReader-> dwCurrentState & SCARD_STATE_UNAVAILABLE)
                              {
                                    currReader->dwEventState &= ~SCARD_STATE_UNAVAILABLE;
                                    currReader->dwEventState |= SCARD_STATE_CHANGED;
                                    dwBreakFlag = 1;
                              }
                        }

      /********** Check for card presence in the reader **************/

                        if (dwState & SCARD_PRESENT)
                        {
                              /* card present but not yet powered up */
                              if (0 == rContext->cardAtrLength)
                                    /* Allow the status thread to convey information */
                                    (void)SYS_USleep(PCSCLITE_STATUS_POLL_RATE + 10);

                              currReader->cbAtr = rContext->cardAtrLength;
                              memcpy(currReader->rgbAtr, rContext->cardAtr,
                                    currReader->cbAtr);
                        }
                        else
                              currReader->cbAtr = 0;

                        /* Card is now absent */
                        if (dwState & SCARD_ABSENT)
                        {
                              currReader->dwEventState |= SCARD_STATE_EMPTY;
                              currReader->dwEventState &= ~SCARD_STATE_PRESENT;
                              currReader->dwEventState &= ~SCARD_STATE_UNAWARE;
                              currReader->dwEventState &= ~SCARD_STATE_IGNORE;
                              currReader->dwEventState &= ~SCARD_STATE_UNKNOWN;
                              currReader->dwEventState &= ~SCARD_STATE_UNAVAILABLE;
                              currReader->dwEventState &= ~SCARD_STATE_ATRMATCH;
                              currReader->dwEventState &= ~SCARD_STATE_MUTE;
                              currReader->dwEventState &= ~SCARD_STATE_INUSE;

                              /* After present the rest are assumed */
                              if (currReader->dwCurrentState & SCARD_STATE_PRESENT)
                              {
                                    currReader->dwEventState |= SCARD_STATE_CHANGED;
                                    dwBreakFlag = 1;
                              }
                        }
                        /* Card is now present */
                        else if (dwState & SCARD_PRESENT)
                        {
                              currReader->dwEventState |= SCARD_STATE_PRESENT;
                              currReader->dwEventState &= ~SCARD_STATE_EMPTY;
                              currReader->dwEventState &= ~SCARD_STATE_UNAWARE;
                              currReader->dwEventState &= ~SCARD_STATE_IGNORE;
                              currReader->dwEventState &= ~SCARD_STATE_UNKNOWN;
                              currReader->dwEventState &= ~SCARD_STATE_UNAVAILABLE;
                              currReader->dwEventState &= ~SCARD_STATE_MUTE;

                              if (currReader->dwCurrentState & SCARD_STATE_EMPTY)
                              {
                                    currReader->dwEventState |= SCARD_STATE_CHANGED;
                                    dwBreakFlag = 1;
                              }

                              if (dwState & SCARD_SWALLOWED)
                              {
                                    currReader->dwEventState |= SCARD_STATE_MUTE;
                                    if (!(currReader->dwCurrentState & SCARD_STATE_MUTE))
                                    {
                                          currReader->dwEventState |= SCARD_STATE_CHANGED;
                                          dwBreakFlag = 1;
                                    }
                              }
                              else
                              {
                                    /* App thinks card is mute but it is not */
                                    if (currReader->dwCurrentState & SCARD_STATE_MUTE)
                                    {
                                          currReader->dwEventState |= SCARD_STATE_CHANGED;
                                          dwBreakFlag = 1;
                                    }
                              }
                        }

                        /* Now figure out sharing modes */
                        if (rContext->readerSharing == -1)
                        {
                              currReader->dwEventState |= SCARD_STATE_EXCLUSIVE;
                              currReader->dwEventState &= ~SCARD_STATE_INUSE;
                              if (currReader->dwCurrentState & SCARD_STATE_INUSE)
                              {
                                    currReader->dwEventState |= SCARD_STATE_CHANGED;
                                    dwBreakFlag = 1;
                              }
                        }
                        else if (rContext->readerSharing >= 1)
                        {
                              /* A card must be inserted for it to be INUSE */
                              if (dwState & SCARD_PRESENT)
                              {
                                    currReader->dwEventState |= SCARD_STATE_INUSE;
                                    currReader->dwEventState &= ~SCARD_STATE_EXCLUSIVE;
                                    if (currReader-> dwCurrentState & SCARD_STATE_EXCLUSIVE)
                                    {
                                          currReader->dwEventState |= SCARD_STATE_CHANGED;
                                          dwBreakFlag = 1;
                                    }
                              }
                        }
                        else if (rContext->readerSharing == 0)
                        {
                              currReader->dwEventState &= ~SCARD_STATE_INUSE;
                              currReader->dwEventState &= ~SCARD_STATE_EXCLUSIVE;

                              if (currReader->dwCurrentState & SCARD_STATE_INUSE)
                              {
                                    currReader->dwEventState |= SCARD_STATE_CHANGED;
                                    dwBreakFlag = 1;
                              }
                              else if (currReader-> dwCurrentState
                                    & SCARD_STATE_EXCLUSIVE)
                              {
                                    currReader->dwEventState |= SCARD_STATE_CHANGED;
                                    dwBreakFlag = 1;
                              }
                        }

                        if (currReader->dwCurrentState == SCARD_STATE_UNAWARE)
                        {
                              /*
                               * Break out of the while .. loop and return status
                               * once all the status's for all readers is met
                               */
                              currReader->dwEventState |= SCARD_STATE_CHANGED;
                              dwBreakFlag = 1;
                        }
                  }     /* End of SCARD_STATE_UNKNOWN */
            }     /* End of SCARD_STATE_IGNORE */

            /* Counter and resetter */
            j++;
            if (j == cReaders)
            {
                  /* go back to the first reader */
                  j = 0;

                  /* Declare all the break conditions */

                  /* Break if UNAWARE is set and all readers have been checked */
                  if (dwBreakFlag == 1)
                        break;

                  if (BLOCK_STATUS_RESUME
                        == psContextMap[dwContextIndex].contextBlockStatus)
                        break;

                  /* Only sleep once for each cycle of reader checks. */
                  dwTime = WaitForPcscdEvent(hContext, dwTime);

                  if (dwTimeout != INFINITE)
                  {
                        /* If time is greater than timeout and all readers have been
                         * checked
                         */
                        if (dwTime <= 0)
                        {
                              rv = SCARD_E_TIMEOUT;
                              goto end;
                        }
                  }
            }
      }
      while (1);

      if (psContextMap[dwContextIndex].contextBlockStatus == BLOCK_STATUS_RESUME)
            rv = SCARD_E_CANCELLED;

end:
      Log1(PCSC_LOG_DEBUG, "Event Loop End");

      (void)SYS_MutexUnLock(psContextMap[dwContextIndex].mMutex);

      PROFILE_END(rv)

      return rv;
}


Generated by  Doxygen 1.6.0   Back to index