SCardListReadersWithDeviceInstanceIdA-Funktion (winscard.h)

Die SCardListReadersWithDeviceInstanceId--Funktion ruft die Liste der Leser ab, die einen Geräteinstanzbezeichner angegeben haben. Diese Funktion wirkt sich nicht auf den Status des Readers aus.

Syntax

LONG SCardListReadersWithDeviceInstanceIdA(
  [in]            SCARDCONTEXT hContext,
  [in]            LPCSTR       szDeviceInstanceId,
  [out, optional] LPSTR        mszReaders,
  [in, out]       LPDWORD      pcchReaders
);

Parameter

[in] hContext

Behandeln Sie dies, um den Ressourcen-Manager-Kontext für die Abfrage zu identifizieren. Sie können den Ressourcen-Manager-Kontext durch einen vorherigen Aufruf der SCardEstablishContext-Funktion festlegen. Dieser Parameter kann nicht NULL-werden.

[in] szDeviceInstanceId

Geräteinstanz-ID des Readers. Sie können diesen Wert abrufen, indem Sie die SCardGetReaderDeviceInstanceId Funktion mit dem Lesenamen aufrufen oder die SetupDiGetDeviceInstanceId Funktion aus dem DDK aufrufen.

[out, optional] mszReaders

Eine mehrfache Zeichenfolge, die die Smartcardleser innerhalb des angegebenen Geräteinstanzbezeichners enthält. Wenn dieser Wert NULL-ist, ignoriert die Funktion die pufferlänge, die im pcchReaders Parameter angegeben wird, schreibt die Länge des Puffers, der zurückgegeben wurde, wenn dieser Parameter nicht NULL- wurde, um pcchReaderszu , und gibt einen Erfolgscode zurück.

[in, out] pcchReaders

Die Länge des mszReaders Puffers in Zeichen. Dieser Parameter empfängt die tatsächliche Länge der Zeichenfolgenstruktur, einschließlich aller endenden NULL-Zeichen. Wenn die Pufferlänge als SCARD_AUTOALLOCATE angegeben wird, wird mszReaders in einen Zeiger in einen Bytezeiger konvertiert und empfängt die Adresse eines Speicherblocks, der die Struktur mit mehreren Zeichenfolgen enthält. Wenn Sie diesen Speicher verwendet haben, haben Sie die Zuordnung mithilfe der SCardFreeMemory-Funktion abgeschlossen.

Rückgabewert

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

Bemerkungen

Diese Funktion wird nicht umgeleitet. Das Aufrufen der SCardListReadersWithDeviceInstanceId- Funktion in einer Remotedesktopsitzung schlägt mit dem SCARD_E_READER_UNAVAILABLE Fehlercode fehl.

Beispiele

szDeviceInstanceIdcchReaderNameLONG     lReturn, lReturn2;

LPTSTR   pmszReaders = NULL;
LPTSTR   pReader = NULL;WCHAR
DWORD    cchReaderName = SCARD_AUTOALLOCATE;

// Retrieve the reader’s name from it’s device instance ID
// hContext was set by a previous call to SCardEstablishContext. 

// szDeviceInstanceId was obtained by calling SetupDiGetDeviceInstanceId
lReturn = SCardListReadersWithDeviceInstanceId (hContext,
                         szDeviceInstanceId,
                         (LPTSTR)&pmszReaders,
                         &cchReaderName);

switch( lReturn )
{
    case SCARD_E_NO_READERS_AVAILABLE:
        printf("No readers have the provided device instance ID.\n");
        // Take appropriate action.
        // ...
        break;

    case SCARD_S_SUCCESS:
        // Do something with the multi string of readers.
        // Output the values.
        // A double-null terminates the list of values.
        pReader = pmszReaders;
        while ( '\0' != *pReader )
        {
            // Display the value.
            printf("Reader: %S\n", pReader );
            // Advance to the next value.
            pReader = pReader + wcslen((wchar_t *)pReader) + 1;
        }
        // Free the memory.
        lReturn2 = SCardFreeMemory( hContext,
                                   pmszReaders );
        if ( SCARD_S_SUCCESS != lReturn2 )
            printf("Failed SCardFreeMemory\n");
        break;

default:
        printf("Failed SCardListReaders\n");
        // Take appropriate action.
        // ...
        break;

Anforderungen