Функция SCardListReadersWithDeviceInstanceIdA (winscard.h)

Статья
11/20/2024

Функция SCardListReadersWithDeviceInstanceId получает список читателей, которые предоставили идентификатор экземпляра устройства. Эта функция не влияет на состояние средства чтения.

Синтаксис

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

Параметры

[in] hContext

Дескриптор, определяющий контекст диспетчера ресурсов для запроса. Контекст диспетчера ресурсов можно задать предыдущим вызовом функции SCardEstablishContext. Этот параметр не может быть значение NULL.

[in] szDeviceInstanceId

Идентификатор экземпляра устройства средства чтения. Это значение можно получить, вызвав функцию SCardGetReaderDeviceInstance Id с именем средства чтения или вызвав функцию SetupDiGetDeviceInstanceId из DDK.

[out, optional] mszReaders

Многострочной, содержащей средства чтения смарт-карт в предоставленном идентификаторе экземпляра устройства. Если это значение NULL, функция игнорирует длину буфера, указанную в параметре pcchReaders, записывает длину буфера, который был бы возвращен, если этот параметр не был NULL для pcchReadersи возвращает код успешного выполнения.

[in, out] pcchReaders

Длина в символах буфера mszReaders. Этот параметр получает фактическую длину структуры с несколькими строками, включая все завершающие символы NULL. Если длина буфера указана как SCARD_AUTOALLOCATE, то mszReaders преобразуется в указатель на указатель байтов и получает адрес блока памяти, содержащего структуру с несколькими строками. Закончив использование этой памяти, разблокировали ее с помощью функции SCardFreeMemory.

Возвращаемое значение

Эта функция возвращает разные значения в зависимости от того, выполнена ли она успешно или завершается сбоем.

Возвращаемый код	Описание
успех	SCARD_S_SUCCESS.
сбоя	Код ошибки. Дополнительные сведения см. в возвращаемых значений смарт-карт.

Замечания

Эта функция не перенаправляется. Вызов функции SCardListReadersWithDeviceInstanceId при сбое в сеансе удаленного рабочего стола с кодом ошибки SCARD_E_READER_UNAVAILABLE.

Примеры


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;

Заметка

Заголовок winscard.h определяет SCardListReadersWithDeviceInstanceId как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 8 [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2012 [только классические приложения]
целевая платформа	Виндоус
заголовка	winscard.h

Поделиться через