SCardConnectW-Funktion (winscard.h)

Artikel
08/27/2023

Die SCardConnect-Funktion stellt eine Verbindung (unter Verwendung eines bestimmten Ressourcen-Manager-Kontexts) zwischen der aufrufenden Anwendung und einer intelligenten Karte her, die von einem bestimmten Leser enthalten ist. Wenn im angegebenen Reader kein Karte vorhanden ist, wird ein Fehler zurückgegeben.

Syntax

LONG SCardConnectW(
  [in]  SCARDCONTEXT  hContext,
  [in]  LPCWSTR       szReader,
  [in]  DWORD         dwShareMode,
  [in]  DWORD         dwPreferredProtocols,
  [out] LPSCARDHANDLE phCard,
  [out] LPDWORD       pdwActiveProtocol
);

Parameter

[in] hContext

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

[in] szReader

Der Name des Lesers, der das Ziel Karte enthält.

[in] dwShareMode

Ein Flag, das angibt, ob andere Anwendungen Verbindungen mit dem Karte herstellen können.

Wert	Bedeutung
SCARD_SHARE_SHARED	Diese Anwendung ist bereit, die Karte mit anderen Anwendungen zu teilen.
SCARD_SHARE_EXCLUSIVE	Diese Anwendung ist nicht bereit, die Karte mit anderen Anwendungen zu teilen.
SCARD_SHARE_DIRECT	Diese Anwendung weist den Reader für seine private Verwendung zu und steuert ihn direkt. Anderen Anwendungen ist der Zugriff darauf gestattet.

[in] dwPreferredProtocols

Eine Bitmaske akzeptabler Protokolle für die Verbindung. Mögliche Werte können mit dem OR-Vorgang kombiniert werden.

Wert	Bedeutung
SCARD_PROTOCOL_T0	T=0 ist ein akzeptables Protokoll.
SCARD_PROTOCOL_T1	T=1 ist ein akzeptables Protokoll.
0	Dieser Parameter kann nur 0 sein, wenn dwShareMode auf SCARD_SHARE_DIRECT festgelegt ist. In diesem Fall wird keine Protokollverhandlung von den Treibern ausgeführt, bis eine IOCTL_SMARTCARD_SET_PROTOCOL-Steuerungsdirektive mit SCardControl gesendet wird.

[out] phCard

Ein Handle, das die Verbindung mit dem intelligenten Karte im angegebenen Leser identifiziert.

[out] pdwActiveProtocol

Ein Flag, das das etablierte aktive Protokoll angibt.

Wert	Bedeutung
SCARD_PROTOCOL_T0	T=0 ist das aktive Protokoll.
SCARD_PROTOCOL_T1	T=1 ist das aktive Protokoll.
SCARD_PROTOCOL_UNDEFINED	SCARD_SHARE_DIRECT wurde angegeben, sodass keine Protokollverhandlung stattgefunden hat. Es ist möglich, dass im Leser keine Karte vorhanden ist.

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.
SCARD_E_NOT_READY	Der Leser konnte keine Verbindung mit dem Karte herstellen.

Hinweise

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

Beispiele

Im folgenden Beispiel wird eine Verbindung mit einem Leser hergestellt. Im Beispiel wird davon ausgegangen, dass hContext ein gültiges Handle vom Typ SCARDCONTEXT ist, das von einem vorherigen Aufruf von SCardEstablishContext empfangen wurde.

SCARDHANDLE     hCardHandle;
LONG            lReturn;
DWORD           dwAP;

lReturn = SCardConnect( hContext, 
                        (LPCTSTR)"Rainbow Technologies SCR3531 0",
                        SCARD_SHARE_SHARED,
                        SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1,
                        &hCardHandle,
                        &dwAP );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardConnect\n");
    exit(1);  // Or other appropriate action.
}

// Use the connection.
// Display the active protocol.
switch ( dwAP )
{
    case SCARD_PROTOCOL_T0:
        printf("Active protocol T0\n"); 
        break;

    case SCARD_PROTOCOL_T1:
        printf("Active protocol T1\n"); 
        break;

    case SCARD_PROTOCOL_UNDEFINED:
    default:
        printf("Active protocol unnegotiated or unknown\n"); 
        break;
}

// Remember to disconnect (by calling SCardDisconnect).
// ...

Hinweis

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

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