Fungsi SCardLocateCardsA (winscard.h)
Fungsi SCardLocateCards mencari pembaca yang tercantum dalam parameter rgReaderStates untuk kartu dengan string ATR yang cocok dengan salah satu nama kartu yang ditentukan dalam mszCards, segera kembali dengan hasilnya.
Sintaks
LONG SCardLocateCardsA(
[in] SCARDCONTEXT hContext,
[in] LPCSTR mszCards,
[in, out] LPSCARD_READERSTATEA rgReaderStates,
[in] DWORD cReaders
);
Parameter
[in] hContext
Handel yang mengidentifikasi konteks resource manager. Konteks resource manager diatur oleh panggilan sebelumnya ke SCardEstablishContext.
[in] mszCards
Beberapa string yang berisi nama kartu yang akan dicari.
[in, out] rgReaderStates
Array struktur SCARD_READERSTATE yang, pada input, menentukan pembaca untuk dicari dan bahwa, pada output, menerima hasilnya.
[in] cReaders
Jumlah elemen dalam array rgReaderStates .
Nilai kembali
Fungsi ini mengembalikan nilai yang berbeda tergantung pada apakah berhasil atau gagal.
Menampilkan kode | Deskripsi |
---|---|
|
SCARD_S_SUCCESS. |
|
Kode kesalahan. Untuk informasi selengkapnya, lihat Nilai Pengembalian Kartu Pintar. |
Keterangan
Layanan ini sangat berguna ketika digunakan bersama dengan SCardGetStatusChange. Jika tidak ada kartu yang cocok yang ditemukan melalui SCardLocateCards, aplikasi panggilan dapat menggunakan SCardGetStatusChange untuk menunggu perubahan ketersediaan kartu.
Fungsi SCardLocateCards adalah fungsi pelacakan kartu pintar . Untuk informasi selengkapnya tentang fungsi pelacakan lainnya, lihat Fungsi Pelacakan Kartu Pintar.
Memanggil fungsi ini harus dilakukan di luar transaksi. Jika aplikasi memulai transaksi dengan fungsi SCardBeginTransaction dan kemudian memanggil fungsi ini, aplikasi akan mengatur ulang parameter hCard (jenis SCARDHANDLE) dari fungsi SCardBeginTransaction .
Windows Server 2008 R2 dan Windows 7: Memanggil fungsi ini dalam transaksi dapat mengakibatkan komputer Anda menjadi tidak responsif.
Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Tidak berlaku.
Contoh
Contoh berikut menunjukkan lokasi kartu pintar.
// 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;
}
Catatan
Header winscard.h mendefinisikan SCardLocateCards sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
Persyaratan | Nilai |
---|---|
Klien minimum yang didukung | Windows XP [hanya aplikasi desktop] |
Server minimum yang didukung | Windows Server 2003 [hanya aplikasi desktop] |
Target Platform | Windows |
Header | winscard.h |
Pustaka | Winscard.lib |
DLL | Winscard.dll |
Lihat juga
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk