SCardIntroduceCardTypeA-Funktion (winscard.h)

Artikel
01/10/2024

Die SCardIntroduceCardType-Funktion führt eine intelligente Karte zum Smart Karte-Subsystem (für den aktiven Benutzer) ein, indem sie der Smart Karte-Datenbank hinzugefügt wird.

Syntax

LONG SCardIntroduceCardTypeA(
  [in]           SCARDCONTEXT hContext,
  [in]           LPCSTR       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 smart Karte.

[in, optional] rgguidInterfaces

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

[in] dwInterfaceCount

Anzahl der Bezeichner im Array "rgguidInterfaces ".

[in] pbAtr

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

[in] pbAtrMask

Optionale Bitmaske, die beim Vergleich der ATRs von Smartcards mit dem in pbAtr bereitgestellten ATR verwendet werden soll. Wenn dieser Wert nicht NULL ist, muss er auf eine Bytezeichenfolge mit der gleichen Länge wie die ATR-Zeichenfolge verweisen, die in pbAtr bereitgestellt wird. Wenn eine bestimmte ATR-Zeichenfolge A mit der in pbAtr bereitgestellten ATR verglichen wird, stimmt sie nur dann überein, 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 0 ist, wird die Länge des ATR durch normale ATR-Analyse bestimmt. Dieser Wert darf nicht 0 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 in einer Remotedesktopsitzung führt nicht zu einem Fehler. Dies bedeutet nur, dass das Ergebnis vom Remotecomputer statt vom lokalen Computer stammt.

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

Um eine intelligente Karte zu entfernen, verwenden Sie SCardForgetCardType.

Beispiele

Das folgende Beispiel zeigt, 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 automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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