SCardIntroduceCardTypeA-Funktion (winscard.h)

Artikel
11/20/2024

Die funktion SCardIntroduceCardType führt eine Smartcard- zum Smartcard-Subsystem (für den aktiven Benutzer) ein, indem sie der Smartcarddatenbankhinzugefü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

Behandeln Sie das Ressourcen-Manager-Kontext. Der Ressourcen-Manager-Kontext wird durch einen vorherigen Aufruf von SCardEstablishContextfestgelegt. Dieser Parameter kann nicht NULL-werden.

[in] szCardName

Name, nach dem der Benutzer die Karte erkennen kann.

[in, optional] pguidPrimaryProvider

Zeiger auf den Bezeichner (GUID) für den primären Dienstanbieter der Smartcard.

[in, optional] rgguidInterfaces

Array von Bezeichnern (GUIDs), die die von der Smartcard unterstützten Schnittstellen identifizieren.

[in] dwInterfaceCount

Anzahl der Bezeichner im rgguidInterfaces Array.

[in] pbAtr

ATR-Zeichenfolge, die für Übereinstimmungszwecke beim Abfragen der Smartcarddatenbank 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 atR verwendet werden soll, der in pbAtr-bereitgestellt wird. Wenn dieser Wert nichtNULL-ist, muss er auf eine Zeichenfolge mit Bytes verweisen, die dieselbe Länge wie die atR-Zeichenfolge in pbAtr-angegeben ist. Wenn eine angegebene ATR-Zeichenfolge A mit dem atR verglichen wird, der in pbAtr-angegeben wird, wird sie nur dann übereinstimmen, wenn A & M = pbAtr, wobei M die angegebene Maske ist, und & bitweise UND darstellt.

[in] cbAtrLen

Länge der ATR- und optionalen ATR-Maske. Wenn dieser Wert null ist, wird die Länge des 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
Erfolg	SCARD_S_SUCCESS.
Fehler	Fehlercode. Weitere Informationen finden Sie unter Smartcard-Rückgabewerte.

Bemerkungen

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 funktion SCardIntroduceCardType ist eine Datenbankverwaltungsfunktion. Weitere Informationen zu anderen Datenbankverwaltungsfunktionen finden Sie unter SmartCard-Datenbankverwaltungsfunktionen.

Um eine Smartcard zu entfernen, verwenden Sie SCardForgetCardType.

Beispiele

Das folgende Beispiel zeigt, wie Sie einen Kartentyp 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");

Anmerkung

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
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