SCardConnectA-Funktion (winscard.h)

Artikel
11/20/2024

Die -Funktion SCardConnect stellt eine Verbindung (mithilfe eines bestimmten Ressourcen-Manager-Kontexts) zwischen der aufrufenden Anwendung und einer Smartcard ein, die von einem bestimmten Reader enthalten sind. Wenn im angegebenen Reader keine Karte vorhanden ist, wird ein Fehler zurückgegeben.

Syntax

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

Parameter

[in] hContext

Ein Handle, das den Kontext des Ressourcen-Managersidentifiziert. Der Ressourcen-Manager-Kontext wird durch einen vorherigen Aufruf von SCardEstablishContextfestgelegt.

[in] szReader

Der Name des Lesers, der die Zielkarte enthält.

[in] dwShareMode

Ein Kennzeichen, das angibt, ob andere Anwendungen Verbindungen mit der Karte bilden 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 übernimmt den Leser für den privaten Gebrauch und kontrolliert ihn direkt. Keine anderen Anwendungen dürfen darauf zugreifen.

[in] dwPreferredProtocols

Eine Bitmaske von akzeptablen Protokollen für die Verbindung. Mögliche Werte können mit dem ODER--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 null 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-Steuerelementdirektive mit SCardControl-gesendet wird.

[out] phCard

Ein Handle, mit dem die Verbindung mit der Smartcard- im angegebenen Lesegerät identifiziert wird.

[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 es keine Karte im Lesegerät gibt.

Rückgabewert

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

Rückgabecode	Beschreibung
Erfolg	SCARD_S_SUCCESS.
Fehler	Fehlercode. Weitere Informationen finden Sie unter Smartcard-Rückgabewerte.
SCARD_E_NOT_READY	Der Leser konnte keine Verbindung mit der Karte herstellen.

Bemerkungen

Die SCardConnect--Funktion ist eine Smartcard- und Lesefunktion Zugriffsfunktion. Weitere Informationen zu anderen Zugriffsfunktionen finden Sie unter Smartcard- und Lesezugriffsfunktionen.

Beispiele

Im folgenden Beispiel wird eine Verbindung mit einem Reader erstellt. Im Beispiel wird davon ausgegangen, dass hContext- ein gültiges Handle vom Typ SCARDCONTEXT, das von einem vorherigen Aufruf an SCardEstablishContextempfangen 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).
// ...

Anmerkung

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 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
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winscard.h
Library	Winscard.lib
DLL-	Winscard.dll

Siehe auch

SCardControl-

SCardDisconnect-

SCardEstablishContext-

SCardReconnect-

Freigeben über