SCardLocateCardsA 関数 (winscard.h)
SCardLocateCards 関数は、rgReaderStates パラメーターにリストされているリーダーを検索し、mszCards で指定されたカード名の 1 つと一致する ATR 文字列を持つカードを検索し、すぐに結果を返します。
構文
LONG SCardLocateCardsA(
[in] SCARDCONTEXT hContext,
[in] LPCSTR mszCards,
[in, out] LPSCARD_READERSTATEA 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 関数の hCard パラメーター (SCARDHANDLE 型) がリセットされます。
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 プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SCardLocateCards を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | winscard.h |
| Library | Winscard.lib |
| [DLL] | Winscard.dll |