Fungsi SCardListCardsA (winscard.h)

Artikel
08/27/2023

Fungsi SCardListCards mencari database kartu pintar dan menyediakan daftar kartu bernama yang sebelumnya diperkenalkan ke sistem oleh pengguna.

Pemanggil menentukan string ATR, sekumpulan pengidentifikasi antarmuka (GUID), atau keduanya. Jika string ATR dan array pengidentifikasi disediakan, kartu yang dikembalikan akan cocok dengan string ATR yang disediakan dan mendukung antarmuka yang ditentukan.

Sintaks

LONG SCardListCardsA(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCBYTE      pbAtr,
  [in]           LPCGUID      rgquidInterfaces,
  [in]           DWORD        cguidInterfaceCount,
  [out]          CHAR         *mszCards,
  [in, out]      LPDWORD      pcchCards
);

Parameter

[in] hContext

Menangani yang mengidentifikasi konteks resource manager untuk kueri. Konteks resource manager dapat diatur oleh panggilan sebelumnya ke SCardEstablishContext.

Jika parameter ini diatur ke NULL, pencarian kartu tidak terbatas pada konteks apa pun.

[in, optional] pbAtr

Alamat string ATR untuk dibandingkan dengan kartu yang diketahui, atau NULL jika tidak ada pencocokan ATR yang akan dilakukan.

[in] rgquidInterfaces

Array pengidentifikasi (GUID), atau NULL jika tidak ada pencocokan antarmuka yang akan dilakukan. Ketika array disediakan, nama kartu akan dikembalikan hanya jika semua pengidentifikasi yang ditentukan didukung oleh kartu.

[in] cguidInterfaceCount

Jumlah entri dalam array rgguidInterfaces . Jika rgguidInterfaces adalah NULL, maka nilai ini diabaikan.

[out] mszCards

Multi-string yang mencantumkan kartu pintar yang ditemukan. Jika nilai ini ADALAH NULL, SCardListCards mengabaikan panjang buffer yang disediakan dalam pcchCards, mengembalikan panjang buffer yang akan dikembalikan jika parameter ini belum NULL ke pcchCards dan kode sukses.

[in, out] pcchCards

Panjang buffer mszCards dalam karakter. Menerima panjang sebenarnya dari struktur multi-string, termasuk semua karakter null berikutnya. Jika panjang buffer ditentukan sebagai SCARD_AUTOALLOCATE, maka mszCards dikonversi ke penunjuk ke penunjuk byte, dan menerima alamat blok memori yang berisi struktur multi-string. Blok memori ini harus dialokasikan dengan SCardFreeMemory.

Mengembalikan nilai

Fungsi ini mengembalikan nilai yang berbeda tergantung pada apakah berhasil atau gagal.

Menampilkan kode	Deskripsi
Berhasil	SCARD_S_SUCCESS.
Kegagalan	Kode kesalahan. Untuk informasi selengkapnya, lihat Nilai Pengembalian Kartu Pintar.

Keterangan

Fungsi ini tidak dialihkan, tetapi memanggil fungsi ketika berada di dalam sesi Desktop Jauh tidak akan mengakibatkan kesalahan. Ini hanya berarti bahwa hasilnya akan berasal dari komputer jarak jauh alih-alih komputer lokal.

Untuk mengembalikan semua kartu pintar yang diperkenalkan ke subsistem, atur pbAtr dan rgguidInterfaces ke NULL.

Fungsi SCardListCards adalah fungsi kueri database. Untuk informasi selengkapnya tentang fungsi kueri database lainnya, lihat Fungsi Kueri Database 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 daftar kartu pintar.

LPTSTR pmszCards = NULL;
LPTSTR pCard;
LONG lReturn;
DWORD cch = SCARD_AUTOALLOCATE;

// Retrieve the list of cards.
lReturn = SCardListCards(NULL,
                         NULL,
                         NULL,
                         NULL,
                         (LPTSTR)&pmszCards,
                         &cch );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardListCards\n");
    exit(1); // Or other appropriate error action
}
// Do something with the multi string of cards.
// Output the values.
// A double-null terminates the list of values.
pCard = pmszCards;
while ( '\0' != *pCard )
{
    // Display the value.
    printf("%S\n", pCard );
    // Advance to the next value.
    pCard = pCard + wcslen(pCard) + 1;
}

// Remember to free pmszCards (by calling SCardFreeMemory).
// ...

Catatan

Header winscard.h mendefinisikan SCardListCards 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