SCardIntroduceCardTypeW-Funktion (winscard.h)

Artikel
01/10/2024

Die SCardIntroduceCardType-Funktion führt eine intelligente Karte in das Smart Karte-Subsystem (für den aktiven Benutzer) ein, indem sie es der Smart Karte-Datenbank hinzufügt.

Syntax

LONG SCardIntroduceCardTypeW(
  [in]           SCARDCONTEXT hContext,
  [in]           LPCWSTR      szCardName,
  [in, optional] LPCGUID      pguidPrimaryProvider,
  [in, optional] LPCGUID      rgguidInterfaces,
  [in]           DWORD        dwInterfaceCount,
  [in]           LPCBYTE      pbAtr,
  [in]           LPCBYTE      pbAtrMask,
  [in]           DWORD        cbAtrLen
);

Parameter

[in] hContext

Handle, das den Ressourcen-Manager-Kontext identifiziert. Der Ressourcen-Manager-Kontext wird durch einen vorherigen Aufruf von SCardEstablishContext festgelegt. Dieser Parameter darf nicht NULL sein.

[in] szCardName

Name, an dem der Benutzer die Karte erkennen kann.

[in, optional] pguidPrimaryProvider

Zeiger auf den Bezeichner (GUID) für den primären Dienstanbieter des intelligenten Karte.

[in, optional] rgguidInterfaces

Array von Bezeichnern (GUIDs), die die vom intelligenten Karte unterstützten Schnittstellen identifizieren.

[in] dwInterfaceCount

Anzahl der Bezeichner im rgguidInterfaces-Array .

[in] pbAtr

ATR-Zeichenfolge, die zu Abgleichszwecken beim Abfragen der Smart Karte-Datenbank verwendet werden kann (weitere Informationen finden Sie unter SCardListCards). Die Länge dieser Zeichenfolge wird durch normale ATR-Analyse bestimmt.

[in] pbAtrMask

Optionale Bitmaske, die verwendet werden soll, wenn die ATRs von Smartcards mit der in pbAtr bereitgestellten ATR verglichen werden. Wenn dieser Wert ungleich NULL ist, muss er auf eine Bytezeichenfolge mit derselben Länge wie die atr-Zeichenfolge verweisen, die in pbAtr bereitgestellt wird. Wenn eine angegebene ATR-Zeichenfolge A mit der in pbAtr bereitgestellten ATR verglichen wird, stimmt sie nur ab, wenn A & M = pbAtr, wobei M die angegebene Maske ist, und & bitweise AND darstellt.

[in] cbAtrLen

Länge der ATR- und optionalen ATR-Maske. Wenn dieser Wert null ist, wird die Länge der ATR durch normale ATR-Analyse bestimmt. Dieser Wert darf nicht null sein, wenn ein pbAtr-Wert angegeben wird.

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

Diese Funktion wird nicht umgeleitet, aber das Aufrufen der Funktion innerhalb einer Remotedesktopsitzung führt nicht zu einem Fehler. Dies bedeutet nur, dass das Ergebnis nicht vom lokalen Computer, sondern vom Remotecomputer stammt.

Die SCardIntroduceCardType-Funktion ist eine Datenbankverwaltungsfunktion. Weitere Informationen zu anderen Datenbankverwaltungsfunktionen finden Sie unter SmartCard-Datenbankverwaltungsfunktionen.

Verwenden Sie SCardForgetCardType, um eine intelligente Karte zu entfernen.

Beispiele

Im folgenden Beispiel wird gezeigt, wie Sie einen Karte Typ einführen. Im Beispiel wird davon ausgegangen, dass hContext ein gültiges Handle ist, das aus einem vorherigen Aufruf der SCardEstablishContext-Funktion abgerufen wurde.

GUID  MyGuid = { 0xABCDEF00,
                 0xABCD,
                 0xABCD,
                 0xAA, 0xBB, 0xCC, 0xDD,
                 0xAA, 0xBB, 0xCC, 0xDD };

static const BYTE MyATR[] =     { 0xaa, 0xbb, 0xcc, 0x00, 0xdd };
static const BYTE MyATRMask[] = { 0xff, 0xff, 0xff, 0x00, 0xff};

LONG            lReturn;

lReturn = SCardIntroduceCardType(hContext, 
                                 L"MyCardName",
                                 &MyGuid,
                                 NULL,    // No interface array
                                 0,       // Interface count = 0
                                 MyATR,
                                 MyATRMask,
                                 sizeof(MyATR));
if ( SCARD_S_SUCCESS != lReturn )
    printf("Failed SCardIntroduceCardType\n");

Hinweis

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