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

Статья
03/13/2024

Функция SCardListReaders предоставляет список читателей в наборе именованных групп читателей, устраняя дублирование.

Вызывающий объект предоставляет список групп читателей и получает список читателей в именованных группах. Нераспознанные имена групп игнорируются. Эта функция возвращает только модули чтения в именованных группах, которые в настоящее время присоединены к системе и доступны для использования.

Синтаксис

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

Параметры

[in] hContext

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

Если для этого параметра задано значение NULL, поиск читателей не ограничивается каким-либо контекстом.

[in, optional] mszGroups

Имена групп читателей, определенных в системе, в виде нескольких строк. Используйте значение NULL для вывода списка всех модулей чтения в системе (то есть группы SCard$AllReaders).

Значение	Значение
SCARD_ALL_READERS TEXT("SCard$AllReaders\000")	Группа используется, когда имя группы не указано при перечислении читателей. Возвращает список всех читателей независимо от того, в какой группе или группах находятся читатели.
SCARD_DEFAULT_READERS TEXT("SCard$DefaultReaders\000")	Группа по умолчанию, в которую добавляются все читатели при добавлении в систему.
SCARD_LOCAL_READERS TEXT("SCard$LocalReaders\000")	Неиспользуемое устаревшее значение. Это внутренне управляемая группа, которую нельзя изменить с помощью API-интерфейсов групп читателей. Он предназначен для использования только для перечисления.
SCARD_SYSTEM_READERS TEXT("SCard$SystemReaders\000")	Неиспользуемое устаревшее значение. Это внутренне управляемая группа, которую нельзя изменить с помощью API-интерфейсов групп читателей. Он предназначен для использования только для перечисления.

[out] mszReaders

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

[in, out] pcchReaders

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

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

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

Возвращаемый код или значение	Описание
Успешно 0 (0x0)	SCARD_S_SUCCESS
Группа не содержит читателей 2148532270 (0x8010002E)	SCARD_E_NO_READERS_AVAILABLE
Указанное средство чтения в настоящее время недоступно для использования 2148532247 (0x80100017)	SCARD_E_READER_UNAVAILABLE
Другое	Код ошибки. Дополнительные сведения см. в разделе Возвращаемые значения смарт-карты.

Функция SCardListReaders — это функция запроса базы данных. Дополнительные сведения о других функциях запросов базы данных см. в разделе Функции запросов к базе данных смарт-карт.

Примеры

В следующем примере показан список модулей чтения.

LPTSTR          pmszReaders = NULL;
LPTSTR          pReader;
LONG            lReturn, lReturn2;
DWORD           cch = SCARD_AUTOALLOCATE;

// Retrieve the list the readers.
// hSC was set by a previous call to SCardEstablishContext.
lReturn = SCardListReaders(hSC,
                           NULL,
                           (LPTSTR)&pmszReaders,
                           &cch );
switch( lReturn )
{
    case SCARD_E_NO_READERS_AVAILABLE:
        printf("Reader is not in groups.\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( hSC,
                                   pmszReaders );
        if ( SCARD_S_SUCCESS != lReturn2 )
            printf("Failed SCardFreeMemory\n");
        break;

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

Примечание

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

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	winscard.h
Библиотека	Winscard.lib
DLL	Winscard.dll