SCardStatusW-Funktion (winscard.h)

Artikel
10/10/2023

Die SCardStatus-Funktion stellt die aktuelle status eines intelligenten Karte in einem Leser bereit. Sie können es jederzeit nach einem erfolgreichen Aufruf von SCardConnect und vor einem erfolgreichen Aufruf von SCardDisconnect aufrufen. Dies wirkt sich nicht auf den Zustand des Leser- oder Lesertreibers aus.

Syntax

LONG SCardStatusW(
  [in]                SCARDHANDLE hCard,
  [out]               LPWSTR      mszReaderNames,
  [in, out, optional] LPDWORD     pcchReaderLen,
  [out, optional]     LPDWORD     pdwState,
  [out, optional]     LPDWORD     pdwProtocol,
  [out]               LPBYTE      pbAtr,
  [in, out, optional] LPDWORD     pcbAtrLen
);

Parameter

[in] hCard

Verweiswert, der von SCardConnect zurückgegeben wird.

[out] mszReaderNames

Liste der Anzeigenamen (mehrere Zeichenfolgen), durch die der aktuell verbundene Reader bekannt ist.

[in, out, optional] pcchReaderLen

Gibt bei der Eingabe die Länge des puffers szReaderName an.

Empfängt bei der Ausgabe die tatsächliche Länge (in Zeichen) der Lesernamenliste, einschließlich des nachfolgenden NULL-Zeichens . Wenn diese Pufferlänge als SCARD_AUTOALLOCATE angegeben wird, wird szReaderName in einen Zeiger auf einen Bytezeiger konvertiert und empfängt die Adresse eines Speicherblocks, der die Struktur mit mehreren Zeichenfolgen enthält.

[out, optional] pdwState

Aktueller Zustand des intelligenten Karte im Leser. Bei Erfolg erhält es einen der folgenden Zustandsindikatoren.

Wert	Bedeutung
SCARD_ABSENT	Es gibt keine Karte im Leser.
SCARD_PRESENT	Es gibt eine Karte im Leser, aber es wurde nicht zur Verwendung in Position gebracht.
SCARD_SWALLOWED	Im Leser befindet sich ein Karte, der zur Verwendung bereit ist. Die Karte wird nicht mit Strom versorgt.
SCARD_POWERED	Der Karte wird mit Strom versorgt, aber der Lesertreiber kennt den Modus des Karte nicht.
SCARD_NEGOTIABLE	Die Karte wurde zurückgesetzt und wartet auf die PTS-Aushandlung.
SCARD_SPECIFIC	Die Karte wurde zurückgesetzt, und es wurden spezifische Kommunikationsprotokolle eingerichtet.

[out, optional] pdwProtocol

Aktuelles Protokoll, falls vorhanden. Der zurückgegebene Wert ist nur sinnvoll, wenn der zurückgegebene Wert von pdwState SCARD_SPECIFIC ist.

Wert	Bedeutung
SCARD_PROTOCOL_RAW	Das Rohdatenübertragungsprotokoll wird verwendet.
SCARD_PROTOCOL_T0	Das ISO 7816/3 T=0-Protokoll wird verwendet.
SCARD_PROTOCOL_T1	Das ISO 7816/3 T=1-Protokoll wird verwendet.

[out] pbAtr

Zeiger auf einen 32-Byte-Puffer, der die ATR-Zeichenfolge vom derzeit eingefügten Karte empfängt, sofern verfügbar.

[in, out, optional] pcbAtrLen

Gibt bei der Eingabe die Länge des pbAtr-Puffers an. Empfängt bei der Ausgabe die Anzahl der Bytes in der ATR-Zeichenfolge (maximal 32 Bytes). Wenn diese Pufferlänge als SCARD_AUTOALLOCATE angegeben wird, wird pbAtr in einen Zeiger auf einen Bytezeiger konvertiert und empfängt die Adresse eines Speicherblocks, der die Struktur mit mehreren Zeichenfolgen enthält.

Rückgabewert

Wenn die Funktion den aktuellen status eines intelligenten Karte in einem Leser erfolgreich bereitstellt, wird der Rückgabewert SCARD_S_SUCCESS.

Wenn die Ausführung der Funktion fehlschlägt, wird ein Fehlercode zurückgegeben. Weitere Informationen finden Sie unter Smartcard-Rückgabewerte.

Hinweise

Die SCardStatus-Funktion ist eine intelligente Karte- und Lesezugriffsfunktion. Weitere Informationen zu anderen Zugriffsfunktionen finden Sie unter Smartcard- und Lesezugriffsfunktionen.

Beispiele

Im folgenden Beispiel wird gezeigt, wie Der Zustand des intelligenten Karte bestimmt wird.

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

Hinweis

Der winscard.h-Header definiert SCardStatus 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

Weitere Informationen

SCardConnect

SCardDisconnect

Freigeben über