SCardLocateCardsA-Funktion (winscard.h)

Artikel
08/27/2023

Die SCardLocateCards-Funktion durchsucht die im Parameter rgReaderStates aufgeführten Leser nach einer Karte mit einer ATR-Zeichenfolge, die einem der in mszCards angegebenen Karte Namen entspricht, 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 suchenden Karten enthält.

[in, out] rgReaderStates

Ein Array von SCARD_READERSTATE Strukturen, die bei der Eingabe die zu durchsuchenden Leser angeben und das Ergebnis bei der Ausgabe 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 Nachverfolgungsfunktion. Weitere Informationen zu anderen Nachverfolgungsfunktionen finden Sie unter Smartcard-Nachverfolgungsfunktionen.

Das Aufrufen dieser Funktion sollte außerhalb einer Transaktion erfolgen. Wenn eine Anwendung eine Transaktion mit der SCardBeginTransaction-Funktion beginnt und dann diese Funktion aufruft, setzt sie den hCard-Parameter (vom Typ SCARDHANDLE) der SCardBeginTransaction-Funktion zurück.

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 die Suche nach 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 nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


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