Fungsi SCardListReadersA (winscard.h)

Artikel
03/08/2023

Fungsi SCardListReaders menyediakan daftar pembaca dalam sekumpulan grup pembaca bernama, menghilangkan duplikat.

Pemanggil menyediakan daftar grup pembaca, dan menerima daftar pembaca dalam grup bernama. Nama grup yang tidak dikenal diabaikan. Fungsi ini hanya mengembalikan pembaca dalam grup bernama yang saat ini dilampirkan ke sistem dan tersedia untuk digunakan.

Sintaks

LONG SCardListReadersA(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCSTR       mszGroups,
  [out]          LPSTR        mszReaders,
  [in, out]      LPDWORD      pcchReaders
);

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 pembaca tidak terbatas pada konteks apa pun.

[in, optional] mszGroups

Nama grup pembaca yang ditentukan ke sistem, sebagai multi-string. Gunakan nilai NULL untuk mencantumkan semua pembaca dalam sistem (yaitu, grup SCard$AllReaders).

Nilai	Makna
SCARD_ALL_READERS TEXT("SCard$AllReaders\000")	Grup yang digunakan saat tidak ada nama grup yang disediakan saat mencantumkan pembaca. Mengembalikan daftar semua pembaca, terlepas dari grup atau grup tempat pembaca berada.
SCARD_DEFAULT_READERS TEXT("SCard$DefaultReaders\000")	Grup default tempat semua pembaca ditambahkan ketika diperkenalkan ke dalam sistem.
SCARD_LOCAL_READERS TEXT("SCard$LocalReaders\000")	Nilai warisan yang tidak digunakan. Ini adalah grup yang dikelola secara internal yang tidak dapat dimodifikasi dengan menggunakan API grup pembaca apa pun. Ini dimaksudkan untuk digunakan hanya untuk enumerasi.
SCARD_SYSTEM_READERS TEXT("SCard$SystemReaders\000")	Nilai warisan yang tidak digunakan. Ini adalah grup yang dikelola secara internal yang tidak dapat dimodifikasi dengan menggunakan API grup pembaca apa pun. Ini dimaksudkan untuk digunakan hanya untuk enumerasi.

[out] mszReaders

Multi-string yang mencantumkan pembaca kartu dalam grup pembaca yang disediakan. Jika nilai ini NULL, SCardListReaders mengabaikan panjang buffer yang disediakan dalam pcchReaders, menulis panjang buffer yang akan dikembalikan jika parameter ini belum NULL ke pcchReaders, dan mengembalikan kode sukses.

[in, out] pcchReaders

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

Nilai kembali

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

Mengembalikan kode/nilai	Deskripsi
Berhasil 0 (0x0)	SCARD_S_SUCCESS
Grup tidak berisi pembaca 2148532270 (0x8010002E)	SCARD_E_NO_READERS_AVAILABLE
Pembaca yang ditentukan saat ini tidak tersedia untuk digunakan 2148532247 (0x80100017)	SCARD_E_READER_UNAVAILABLE
Lainnya	Kode kesalahan. Untuk informasi selengkapnya, lihat Nilai Pengembalian Kartu Pintar.

Keterangan

Fungsi SCardListReaders adalah fungsi kueri database. Untuk informasi selengkapnya tentang fungsi kueri database lainnya, lihat Fungsi Kueri Database Kartu Pintar.

Contoh

Contoh berikut menunjukkan daftar pembaca.

LPTSTR          pmszReaders = NULL;
LPTSTR          pReader;
LONG            lReturn, lReturn2;
DWORD           cch = SCARD_AUTOALLOCATE;

// Retrieve the list the readers.
// hSC was set by a previous call to SCardEstablishContext.
lReturn = SCardListReaders(hSC,
                           NULL,
                           (LPTSTR)&pmszReaders,
                           &cch );
switch( lReturn )
{
    case SCARD_E_NO_READERS_AVAILABLE:
        printf("Reader is not in groups.\n");
        // Take appropriate action.
        // ...
        break;

    case SCARD_S_SUCCESS:
        // Do something with the multi string of readers.
        // Output the values.
        // A double-null terminates the list of values.
        pReader = pmszReaders;
        while ( '\0' != *pReader )
        {
            // Display the value.
            printf("Reader: %S\n", pReader );
            // Advance to the next value.
            pReader = pReader + wcslen((wchar_t *)pReader) + 1;
        }
        // Free the memory.
        lReturn2 = SCardFreeMemory( hSC,
                                   pmszReaders );
        if ( SCARD_S_SUCCESS != lReturn2 )
            printf("Failed SCardFreeMemory\n");
        break;

default:
        printf("Failed SCardListReaders\n");
        // Take appropriate action.
        // ...
        break;
}

Catatan

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