SCardStatusA-Funktion (winscard.h)

Artikel
03/04/2024

Die SCardStatus-Funktion stellt die aktuelle status eines intelligenten Karte in einem Reader bereit. Sie können ihn jederzeit nach einem erfolgreichen Aufruf von SCardConnect und vor einem erfolgreichen Aufruf von SCardDisconnect aufrufen. Der Zustand des Reader- oder Readertreibers wird nicht beeinflusst.

Syntax

LONG SCardStatusA(
  [in]                SCARDHANDLE hCard,
  [out]               LPSTR       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), mit denen der aktuell verbundene Reader bekannt ist.

[in, out, optional] pcchReaderLen

Gibt bei der Eingabe die Länge des szReaderName-Puffers 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 der intelligenten Karte im Reader. Bei Erfolg empfängt sie einen der folgenden Statusindikatoren.

Wert	Bedeutung
SCARD_ABSENT	Es gibt keine Karte im Reader.
SCARD_PRESENT	Es gibt eine Karte im Reader, aber es wurde nicht zur Verwendung in position verschoben.
SCARD_SWALLOWED	Es gibt ein Karte in der Position des Lesers, der verwendet werden kann. Die Karte ist nicht mit Strom versorgt.
SCARD_POWERED	Der Karte wird mit Strom versorgt, aber der Readertreiber ist sich des Modus der Karte nicht bewusst.
SCARD_NEGOTIABLE	Die Karte wurde zurückgesetzt und wartet auf eine 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_SPECIFICMODE 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 aktuell 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 in einen Bytezeiger konvertiert und empfängt die Adresse eines Speicherblocks, der die Struktur mit mehreren Zeichenfolgen enthält.

Rückgabewert

Wenn die Funktion erfolgreich die aktuelle status eines intelligenten Karte in einem Reader 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. 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 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

SCardConnect

SCardDisconnect

Freigeben über