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

Статья
11/20/2024

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

Синтаксис

LONG SCardListReaderGroupsW(
  [in]      SCARDCONTEXT hContext,
  [out]     LPWSTR       mszGroups,
  [in, out] LPDWORD      pcchGroups
);

Параметры

[in] hContext

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

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

[out] mszGroups

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

Ценность	Значение
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 группы чтения. Он предназначен только для перечисления.

[in, out] pcchGroups

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

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

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

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

Замечания

Возвращается группа, только если она содержит по крайней мере одну чтения. Это включает группу SCard$DefaultReaders. Невозможно вернуть группу SCard$AllReaders, так как она существует только неявно.

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

Примеры

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

LPTSTR          pmszReaderGroups = NULL;
LPTSTR          pReaderGroup;
LONG            lReturn;
DWORD           cch = SCARD_AUTOALLOCATE;
    
// Retrieve the list the reader groups.
// hSC was set by a previous call to SCardEstablishContext.
lReturn = SCardListReaderGroups(hSC,
                                (LPTSTR)&pmszReaderGroups,
                                &cch );
if ( SCARD_S_SUCCESS != lReturn )
    printf("Failed SCardListReaderGroups\n");
else
{
    // Do something with the multi string of reader groups.
    // Output the values.
    // A double-null terminates the list of values.
    pReaderGroup = pmszReaderGroups;
    while ( '\0' != *pReaderGroup )
    {
        // Display the value.
        printf("%S\n", pReaderGroup );
        // Advance to the next value.
        pReaderGroup = pReaderGroup + wcslen((wchar_t *) pReaderGroup) + 1;
    }

    // Remember to free pmszReaderGroups by a call to SCardFreeMemory.
    // ...
}

Заметка

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

Требования

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