Freigeben über


SCardLocateCardsA-Funktion (winscard.h)

Die SCardLocateCards-Funktion durchsucht die im rgReaderStates-Parameter aufgeführten Leser nach einem Karte mit einer ATR-Zeichenfolge, die mit einem der in mszCards angegebenen Karte Namen übereinstimmt, und gibt sofort mit dem Ergebnis zurück.

Syntax

LONG SCardLocateCardsA(
  [in]      SCARDCONTEXT         hContext,
  [in]      LPCSTR               mszCards,
  [in, out] LPSCARD_READERSTATEA rgReaderStates,
  [in]      DWORD                cReaders
);

Parameter

[in] hContext

Ein Handle, das den Ressourcen-Manager-Kontext identifiziert. Der Ressourcen-Manager-Kontext wird durch einen vorherigen Aufruf von SCardEstablishContext festgelegt.

[in] mszCards

Eine mehrfache Zeichenfolge, die die Namen der zu durchsuchenden Karten enthält.

[in, out] rgReaderStates

Ein Array von SCARD_READERSTATE Strukturen, die bei der Eingabe die zu durchsuchenden Leser angeben und bei der Ausgabe das Ergebnis empfängt.

[in] cReaders

Die Anzahl der Elemente im rgReaderStates-Array .

Rückgabewert

Diese Funktion gibt unterschiedliche Werte zurück, je nachdem, ob sie erfolgreich ist oder fehlschlägt.

Rückgabecode BESCHREIBUNG
Erfolgreich
SCARD_S_SUCCESS.
Fehler
Ein Fehlercode. Weitere Informationen finden Sie unter Smartcard-Rückgabewerte.

Hinweise

Dieser Dienst ist besonders nützlich, wenn er in Verbindung mit SCardGetStatusChange verwendet wird. Wenn keine übereinstimmenden Karten mithilfe von SCardLocateCards gefunden werden, kann die aufrufende Anwendung SCardGetStatusChange verwenden, um auf Karte Verfügbarkeitsänderungen zu warten.

Die SCardLocateCards-Funktion ist eine intelligente Karte Tracking-Funktion. Weitere Informationen zu anderen Nachverfolgungsfunktionen finden Sie unter Smartcard-Nachverfolgungsfunktionen.

Der Aufruf dieser Funktion sollte außerhalb einer Transaktion erfolgen. Wenn eine Anwendung eine Transaktion mit der SCardBeginTransaction-Funktion beginnt und dann diese Funktion aufruft, wird der hCard-Parameter (vom Typ SCARDHANDLE) der SCardBeginTransaction-Funktion zurückgesetzt.

Windows Server 2008 R2 und Windows 7: Das Aufrufen dieser Funktion innerhalb einer Transaktion kann dazu führen, dass Ihr Computer nicht mehr reagiert.

Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Nicht zutreffend.

Beispiele

Das folgende Beispiel zeigt das Auffinden von Smartcards.

// Copyright (C) Microsoft. All rights reserved. 
#include <stdio.h>
#include <winscard.h>
#include <tchar.h>
#pragma comment(lib, "winscard.lib")

HRESULT __cdecl main()
{
HRESULT           hr = S_OK;
LPTSTR            szReaders, szRdr;
DWORD             cchReaders = SCARD_AUTOALLOCATE;
DWORD             dwI, dwRdrCount;
SCARD_READERSTATE rgscState[MAXIMUM_SMARTCARD_READERS];
TCHAR             szCard[MAX_PATH];
SCARDCONTEXT      hSC;
LONG              lReturn;

// Establish the card to watch for.
// Multiple cards can be looked for, but
// this sample looks for only one card.
_tcscat_s ( szCard, MAX_PATH * sizeof(TCHAR), TEXT("GemSAFE"));
szCard[lstrlen(szCard) + 1] = 0;  // Double trailing zero.

// Establish a context.
lReturn = SCardEstablishContext(SCARD_SCOPE_USER,
                                NULL,
                                NULL,
                                &hSC );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardEstablishContext\n");
    exit(1);
}

// Determine which readers are available.
lReturn = SCardListReaders(hSC,
                           NULL,
                           (LPTSTR)&szReaders,
                           &cchReaders );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardListReaders\n");
    exit(1);
}
// Place the readers into the state array.
szRdr = szReaders;
for ( dwI = 0; dwI < MAXIMUM_SMARTCARD_READERS; dwI++ )
{
    if ( 0 == *szRdr )
        break;
    rgscState[dwI].szReader = szRdr;
    rgscState[dwI].dwCurrentState = SCARD_STATE_UNAWARE;
    szRdr += lstrlen(szRdr) + 1;
}
dwRdrCount = dwI;

// If any readers are available, proceed.
if ( 0 != dwRdrCount )
{
  for (;;)
  { 
    // Look for the card.
    lReturn = SCardLocateCards(hSC,
                               szCard,
                               rgscState,
                               dwRdrCount );
    if ( SCARD_S_SUCCESS != lReturn )
    {
        printf("Failed SCardLocateCards\n");
        exit(1);
    }

    // Look through the array of readers.
    for ( dwI=0; dwI < dwRdrCount; dwI++)
    {
        if ( 0 != ( SCARD_STATE_ATRMATCH & 
                    rgscState[dwI].dwEventState))
        {
           _tprintf( TEXT("Card '%s' found in reader '%s'.\n"),
                     szCard,
                     rgscState[dwI].szReader );
            SCardFreeMemory( hSC,
                             szReaders );
            return 0;  // Context will be release automatically.
        }
        // Update the state.
        rgscState[dwI].dwCurrentState = rgscState[dwI].dwEventState;
    }

  // Card not found yet; wait until there is a change.
  lReturn = SCardGetStatusChange(hSC,
                                 INFINITE, // infinite wait
                                 rgscState,
                                 dwRdrCount );
  if ( SCARD_S_SUCCESS != lReturn )
  {
    printf("Failed SCardGetStatusChange\n");
    exit(1);
  }
 }  // for (;;)
}
else
    printf("No readers available\n");

// Release the context.
lReturn = SCardReleaseContext(hSC);
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardReleaseContext\n");
    exit(1);
}

SCardFreeMemory( hSC,
                 szReaders );

return hr;
}

Hinweis

Der winscard.h-Header definiert SCardLocateCards als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile winscard.h
Bibliothek Winscard.lib
DLL Winscard.dll

Weitere Informationen

SCARD_READERSTATE

SCardCancel

SCardEstablishContext

SCardGetStatusChange