Fungsi SCardListReaderGroupsW (winscard.h)

Artikel
08/27/2023

Fungsi SCardListReaderGroups menyediakan daftar grup pembaca yang sebelumnya telah diperkenalkan ke sistem.

Sintaks

LONG SCardListReaderGroupsW(
  [in]      SCARDCONTEXT hContext,
  [out]     LPWSTR       mszGroups,
  [in, out] LPDWORD      pcchGroups
);

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

[out] mszGroups

Multi-string yang mencantumkan grup pembaca yang ditentukan ke sistem dan tersedia untuk pengguna saat ini di terminal saat ini. Jika nilai ini ADALAH NULL, SCardListReaderGroups mengabaikan panjang buffer yang disediakan dalam pcchGroups, menulis panjang buffer yang akan dikembalikan jika parameter ini belum NULL ke pcchGroups, dan mengembalikan kode sukses.

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.

[in, out] pcchGroups

Panjang buffer mszGroups dalam karakter, dan menerima panjang sebenarnya dari struktur multi-string, termasuk semua karakter null berikutnya. Jika panjang buffer ditentukan sebagai SCARD_AUTOALLOCATE, maka mszGroups 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.

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

Keterangan

Grup dikembalikan hanya jika berisi setidaknya satu pembaca. Ini termasuk grup SCard$DefaultReaders. Grup SCard$AllReaders tidak dapat dikembalikan, karena hanya ada secara implisit.

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

Contoh

Contoh berikut menunjukkan daftar grup pembaca.

LPTSTR          pmszReaderGroups = NULL;
LPTSTR          pReaderGroup;
LONG            lReturn;
DWORD           cch = SCARD_AUTOALLOCATE;
    
// Retrieve the list the reader groups.
// hSC was set by a previous call to SCardEstablishContext.
lReturn = SCardListReaderGroups(hSC,
                                (LPTSTR)&pmszReaderGroups,
                                &cch );
if ( SCARD_S_SUCCESS != lReturn )
    printf("Failed SCardListReaderGroups\n");
else
{
    // Do something with the multi string of reader groups.
    // Output the values.
    // A double-null terminates the list of values.
    pReaderGroup = pmszReaderGroups;
    while ( '\0' != *pReaderGroup )
    {
        // Display the value.
        printf("%S\n", pReaderGroup );
        // Advance to the next value.
        pReaderGroup = pReaderGroup + wcslen((wchar_t *) pReaderGroup) + 1;
    }

    // Remember to free pmszReaderGroups by a call to SCardFreeMemory.
    // ...
}

Catatan

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