SCardLocateCardsW 函数 (winscard.h)
SCardLocateCards 函数在 rgReaderStates 参数中列出的读取器中搜索卡，该字符串与 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 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | winscard.h |
| Library | Winscard.lib |
| DLL | Winscard.dll |