SCardLocateCardsW 函数 （winscard.h）
SCardLocateCards 函数在 rgReaderStates 参数中搜索 ATR 字符串 匹配 mszCards中指定的卡片名称之一的卡片，并立即返回结果。
语法
LONG SCardLocateCardsW(
[in] SCARDCONTEXT hContext,
[in] LPCWSTR mszCards,
[in, out] LPSCARD_READERSTATEW rgReaderStates,
[in] DWORD cReaders
);
参数
[in] hContext
标识 资源管理器上下文的句柄。 资源管理器上下文由上一次调用 SCardEstablishContext设置。
[in] mszCards
一个包含要搜索的卡片名称的多个字符串。
[in, out] rgReaderStates
一个由 SCARD_READERSTATE 结构构成的数组，在输入中指定要搜索的读取器，并在输出中接收结果。
[in] cReaders
rgReaderStates 数组中的元素数。
返回值
此函数返回不同的值，具体取决于它是成功还是失败。
| 返回代码 | 描述 |
|---|---|
|
SCARD_S_SUCCESS。 |
|
错误代码。 有关详细信息，请参阅 智能卡返回值。 |
言论
与 SCardGetStatusChange结合使用时，此服务特别有用。 如果 SCardLocateCards找不到匹配卡，则调用应用程序可以使用 SCardGetStatusChange 等待卡可用性更改。
SCardLocateCards 函数是 智能卡 跟踪函数。 有关其他跟踪函数的详细信息，请参阅 智能卡跟踪函数。
应在事务之外调用此函数。 如果应用程序使用 SCardBeginTransaction 函数开始事务，然后调用此函数，则会重置 SCardBeginTransaction 函数的 SCARDHANDLE类型的 hCard 参数。
Windows Server 2008 R2 和 Windows 7：在事务中调用此函数可能会导致计算机无响应。
Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP：不适用。
例子
以下示例演示如何查找智能卡。
// Copyright (C) Microsoft. All rights reserved.
#include <stdio.h>
#include <winscard.h>
#include <tchar.h>
#pragma comment(lib, "winscard.lib")
HRESULT __cdecl main()
{
HRESULT hr = S_OK;
LPTSTR szReaders, szRdr;
DWORD cchReaders = SCARD_AUTOALLOCATE;
DWORD dwI, dwRdrCount;
SCARD_READERSTATE rgscState[MAXIMUM_SMARTCARD_READERS];
TCHAR szCard[MAX_PATH];
SCARDCONTEXT hSC;
LONG lReturn;
// Establish the card to watch for.
// Multiple cards can be looked for, but
// this sample looks for only one card.
_tcscat_s ( szCard, MAX_PATH * sizeof(TCHAR), TEXT("GemSAFE"));
szCard[lstrlen(szCard) + 1] = 0; // Double trailing zero.
// Establish a context.
lReturn = SCardEstablishContext(SCARD_SCOPE_USER,
NULL,
NULL,
&hSC );
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardEstablishContext\n");
exit(1);
}
// Determine which readers are available.
lReturn = SCardListReaders(hSC,
NULL,
(LPTSTR)&szReaders,
&cchReaders );
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardListReaders\n");
exit(1);
}
// Place the readers into the state array.
szRdr = szReaders;
for ( dwI = 0; dwI < MAXIMUM_SMARTCARD_READERS; dwI++ )
{
if ( 0 == *szRdr )
break;
rgscState[dwI].szReader = szRdr;
rgscState[dwI].dwCurrentState = SCARD_STATE_UNAWARE;
szRdr += lstrlen(szRdr) + 1;
}
dwRdrCount = dwI;
// If any readers are available, proceed.
if ( 0 != dwRdrCount )
{
for (;;)
{
// Look for the card.
lReturn = SCardLocateCards(hSC,
szCard,
rgscState,
dwRdrCount );
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardLocateCards\n");
exit(1);
}
// Look through the array of readers.
for ( dwI=0; dwI < dwRdrCount; dwI++)
{
if ( 0 != ( SCARD_STATE_ATRMATCH &
rgscState[dwI].dwEventState))
{
_tprintf( TEXT("Card '%s' found in reader '%s'.\n"),
szCard,
rgscState[dwI].szReader );
SCardFreeMemory( hSC,
szReaders );
return 0; // Context will be release automatically.
}
// Update the state.
rgscState[dwI].dwCurrentState = rgscState[dwI].dwEventState;
}
// Card not found yet; wait until there is a change.
lReturn = SCardGetStatusChange(hSC,
INFINITE, // infinite wait
rgscState,
dwRdrCount );
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardGetStatusChange\n");
exit(1);
}
} // for (;;)
}
else
printf("No readers available\n");
// Release the context.
lReturn = SCardReleaseContext(hSC);
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardReleaseContext\n");
exit(1);
}
SCardFreeMemory( hSC,
szReaders );
return hr;
}
注意
winscard.h 标头将 SCardLocateCards 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows XP [仅限桌面应用] |
| 支持的最低服务器 | Windows Server 2003 [仅限桌面应用] |
| 目标平台 | 窗户 |
| 标头 | winscard.h |
| 库 | Winscard.lib |
| DLL | Winscard.dll |