Функция 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.
Failure
Код ошибки. Дополнительные сведения см. в разделе Возвращаемые значения смарт-карты.

Комментарии

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

Чтобы вернуть все смарт-карты, представленные в подсистеме, задайте для 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

См. также раздел

SCardEstablishContext

SCardFreeMemory

SCardGetProviderId

SCardListInterfaces

SCardListReaderGroups

SCardListReaders