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
識別資源管理員內容之
[in] mszCards
包含要搜尋之卡片名稱的多個字串。
[in, out] rgReaderStates
SCARD_READERSTATE 結構的陣列，在輸入上指定要搜尋的讀取器，並在輸出中接收結果。
[in] cReaders
rgReaderStates 陣列中的元素數目。
傳回值
此函式會根據它是否成功或失敗，傳回不同的值。
| 傳回碼 | 描述 |
|---|---|
|
SCARD_S_SUCCESS。 |
|
錯誤碼。 如需詳細資訊，請參閱 |
言論
此服務與 SCardGetStatusChange 搭配使用時特別有用，。 如果透過 SCardLocateCards找不到相符的卡片，則呼叫應用程式可以使用 SCardGetStatusChange 等候卡片可用性變更。
SCardLocateCards 函式是 智慧卡 追蹤函式。 如需其他追蹤函式的詳細資訊，請參閱 智慧卡追蹤函式。
呼叫此函式應該在異動之外完成。 如果應用程式以 SCardBeginTransaction 函式開始交易，然後呼叫此函式，它會重設 hCard 參數（類型為 SCARDHANDLE），SCardBeginTransaction 函式。
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 標頭會根據 UNICODE 預處理器常數的定義，將 SCardLocateCards 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 支援的最低伺服器 | Windows Server 2003 [僅限傳統型應用程式] |
| 目標平臺 | 窗戶 |
| 標頭 | winscard.h |
| 連結庫 | Winscard.lib |
| DLL | Winscard.dll |