Функция SCardListCardsA (winscard.h)
Функция 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
Дескриптор, идентифицирующий контекст Resource Manager для запроса. Контекст диспетчера ресурсов можно задать с помощью предыдущего вызова SCardEstablishContext.
Если для этого параметра задано значение NULL, поиск карточек не ограничивается каким-либо контекстом.
[in, optional] pbAtr
Адрес строки ATR для сравнения с известными карточками или значение NULL , если сопоставление ATR не выполняется.
[in] rgquidInterfaces
Массив идентификаторов (GUID) или NULL , если сопоставление интерфейса не выполняется. При указании массива имя карта возвращается только в том случае, если все указанные идентификаторы поддерживаются карта.
[in] cguidInterfaceCount
Число записей в массиве rgguidInterfaces . Если rgguidInterfaces имеет значение NULL, то это значение игнорируется.
[out] mszCards
Многостроочный список найденных смарт-карт . Если это значение равно NULL, SCardListCards игнорирует длину буфера, указанную в pcchCards, возвращая длину буфера, которая была бы возвращена, если бы этот параметр не имел значение NULL для pcchCards и код успешного выполнения.
[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 [только классические приложения] |
Целевая платформа | Windows |
Header | winscard.h |
Библиотека | Winscard.lib |
DLL | Winscard.dll |
См. также раздел
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе:Отправить и просмотреть отзыв по