Fungsi SCardListReadersWithDeviceInstanceIdA (winscard.h)

Fungsi SCardListReadersWithDeviceInstanceId mendapatkan daftar pembaca yang telah menyediakan pengidentifikasi instans perangkat. Fungsi ini tidak memengaruhi status pembaca.

Sintaks

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

Parameter

[in] hContext

Menangani yang mengidentifikasi konteks resource manager untuk kueri. Anda dapat mengatur konteks resource manager dengan panggilan sebelumnya ke fungsi SCardEstablishContext . Parameter ini tidak boleh NULL.

[in] szDeviceInstanceId

ID instans perangkat pembaca. Anda bisa mendapatkan nilai ini dengan memanggil fungsi SCardGetReaderDeviceInstanceId dengan nama pembaca atau dengan memanggil fungsi SetupDiGetDeviceInstanceId dari DDK.

[out, optional] mszReaders

Multi-string yang berisi pembaca kartu pintar dalam pengidentifikasi instans perangkat yang disediakan. Jika nilai ini NULL, maka fungsi mengabaikan panjang buffer yang disediakan dalam parameter pcchReaders , menulis panjang buffer yang akan dikembalikan jika parameter ini belum NULL ke pcchReaders, dan mengembalikan kode sukses.

[in, out] pcchReaders

Panjangnya, dalam karakter, dari buffer mszReaders . Parameter ini menerima panjang aktual struktur multi-string, termasuk semua karakter null yang mengakhiri. 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. Setelah Anda selesai menggunakan memori ini, batalkan alokasinya dengan menggunakan fungsi 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

Fungsi ini tidak dialihkan. Memanggil fungsi SCardListReadersWithDeviceInstanceId saat di dalam sesi Desktop Jauh gagal dengan kode kesalahan SCARD_E_READER_UNAVAILABLE.

Contoh

szDeviceInstanceIdcchReaderNameLONG     lReturn, lReturn2;

LPTSTR   pmszReaders = NULL;
LPTSTR   pReader = NULL;WCHAR
DWORD    cchReaderName = SCARD_AUTOALLOCATE;

// Retrieve the reader’s name from it’s device instance ID
// hContext was set by a previous call to SCardEstablishContext. 

// szDeviceInstanceId was obtained by calling SetupDiGetDeviceInstanceId
lReturn = SCardListReadersWithDeviceInstanceId (hContext,
                         szDeviceInstanceId,
                         (LPTSTR)&pmszReaders,
                         &cchReaderName);

switch( lReturn )
{
    case SCARD_E_NO_READERS_AVAILABLE:
        printf("No readers have the provided device instance ID.\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( hContext,
                                   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 SCardListReadersWithDeviceInstanceId sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosedur 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

Klien minimum yang didukung	Windows 8 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2012 [hanya aplikasi desktop]
Target Platform	Windows
Header	winscard.h