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

Статья
11/20/2024

Функция SCardListCards выполняет поиск базы данных смарт-карт и предоставляет список именованных карточек, представленных в системе пользователем.

Вызывающий объект задает строковуюATR, набор идентификаторов интерфейса (GUID) или оба. Если указана строка ATR и массив идентификаторов, возвращенные карточки будут соответствовать заданной строке ATR и поддерживать указанные интерфейсы.

Синтаксис

LONG SCardListCardsA(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCBYTE      pbAtr,
  [in]           LPCGUID      rgquidInterfaces,
  [in]           DWORD        cguidInterfaceCount,
  [out]          CHAR         *mszCards,
  [in, out]      LPDWORD      pcchCards
);

Параметры

[in] hContext

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

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

[in, optional] pbAtr

Адрес строки ATR для сравнения с известными карточками или null, если сопоставление ATR не выполняется.

[in] rgquidInterfaces

Массив идентификаторов (GUID) или NULL, если сопоставление интерфейса не выполняется. При указании массива имя карточки будет возвращено только в том случае, если все указанные идентификаторы поддерживаются картой.

[in] cguidInterfaceCount

Количество записей в массиве rgguidInterfaces. Если rgguidInterfacesNULL, это значение игнорируется.

[out] mszCards

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

[in, out] pcchCards

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

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

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

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

Замечания

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

Чтобы вернуть все смарт-карты, введенные в подсистему, задайте pbAtr и rgguidInterfaces значение NULL.

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

Вызов этой функции должен выполняться за пределами транзакции. Если приложение начинает транзакцию с функцией SCardBeginTransaction, а затем вызывает эту функцию, она сбрасывает параметр hCard (типа SCARDHANDLE) функции SCardBeginTransaction.

Windows Server 2008 R2 и Windows 7: вызов этой функции в рамках транзакции может привести к тому, что компьютер не отвечает.

Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Неприменимо.

Примеры

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

LPTSTR pmszCards = NULL;
LPTSTR pCard;
LONG lReturn;
DWORD cch = SCARD_AUTOALLOCATE;

// Retrieve the list of cards.
lReturn = SCardListCards(NULL,
                         NULL,
                         NULL,
                         NULL,
                         (LPTSTR)&pmszCards,
                         &cch );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardListCards\n");
    exit(1); // Or other appropriate error action
}
// Do something with the multi string of cards.
// Output the values.
// A double-null terminates the list of values.
pCard = pmszCards;
while ( '\0' != *pCard )
{
    // Display the value.
    printf("%S\n", pCard );
    // Advance to the next value.
    pCard = pCard + wcslen(pCard) + 1;
}

// Remember to free pmszCards (by calling SCardFreeMemory).
// ...

Заметка

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

Требования

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