Fungsi SetupDiGetClassDevsExW (setupapi.h)

Artikel
03/15/2023

Fungsi SetupDiGetClassDevsEx mengembalikan handel ke kumpulan informasi perangkat yang berisi elemen informasi perangkat yang diminta untuk komputer lokal atau jarak jauh.

Sintaks

WINSETUPAPI HDEVINFO SetupDiGetClassDevsExW(
  [in, optional] const GUID *ClassGuid,
  [in, optional] PCWSTR     Enumerator,
  [in, optional] HWND       hwndParent,
  [in]           DWORD      Flags,
  [in, optional] HDEVINFO   DeviceInfoSet,
  [in, optional] PCWSTR     MachineName,
                 PVOID      Reserved
);

Parameter

[in, optional] ClassGuid

Penunjuk ke GUID untuk kelas penyiapan perangkat atau kelas antarmuka perangkat. Penunjuk ini bersifat opsional dan dapat berupa NULL. Jika nilai GUID tidak digunakan untuk memilih perangkat, atur ClassGuid ke NULL. Untuk informasi selengkapnya tentang cara menggunakan ClassGuid, lihat bagian Keterangan berikut ini.

[in, optional] Enumerator

Penunjuk ke string yang dihentikan NULL yang menentukan:

Pengidentifikasi (ID) enumerator Plug and Play (PnP). ID ini dapat menjadi pengidentifikasi unik global (GUID) enumerator atau nama simbolis. Misalnya, "PCI" dapat digunakan untuk menentukan enumerator PCI PnP. Contoh lain dari nama simbolis untuk enumerator PnP termasuk "USB", "PCMCIA", dan "SCSI".
ID instans perangkat PnP. Saat menentukan ID instans perangkat PnP, DIGCF_DEVICEINTERFACE harus diatur dalam parameter Bendera.

Penunjuk ini bersifat opsional dan dapat berupa NULL. Jika nilai Enumerator tidak digunakan untuk memilih perangkat, atur Enumerator ke NULL

Untuk informasi selengkapnya tentang cara mengatur nilai Enumerator , lihat bagian Keterangan berikut ini.

[in, optional] hwndParent

Handel ke jendela tingkat atas yang akan digunakan untuk antarmuka pengguna yang terkait dengan penginstalan instans perangkat dalam kumpulan informasi perangkat. Handel ini bersifat opsional dan dapat berupa NULL.

[in] Flags

Variabel jenis DWORD yang menentukan opsi kontrol yang memfilter elemen informasi perangkat yang ditambahkan ke kumpulan informasi perangkat. Parameter ini bisa menjadi bitwise ATAU dari satu atau beberapa bendera berikut. Untuk informasi selengkapnya tentang menggabungkan opsi kontrol ini, lihat bagian Keterangan berikut ini.

DIGCF_ALLCLASSES

Mengembalikan daftar perangkat yang diinstal untuk kelas penyiapan perangkat atau kelas antarmuka perangkat yang ditentukan.

DIGCF_DEVICEINTERFACE

Mengembalikan perangkat yang mendukung antarmuka perangkat untuk kelas antarmuka perangkat yang ditentukan. Bendera ini harus diatur dalam parameter Bendera jika parameter Enumerator menentukan ID instans perangkat.

DIGCF_DEFAULT

Kembalikan hanya perangkat yang terkait dengan antarmuka perangkat default sistem, jika perangkat diatur, untuk kelas antarmuka perangkat yang ditentukan.

DIGCF_PRESENT

Mengembalikan hanya perangkat yang saat ini ada.

DIGCF_PROFILE

Mengembalikan hanya perangkat yang merupakan bagian dari profil perangkat keras saat ini.

[in, optional] DeviceInfoSet

Handel ke informasi perangkat yang ada yang diatur ke SetupDiGetClassDevsEx menambahkan elemen informasi perangkat yang diminta. Parameter ini bersifat opsional dan dapat diatur ke NULL. Untuk informasi selengkapnya tentang menggunakan parameter ini, lihat bagian Keterangan berikut ini.

[in, optional] MachineName

Penunjuk ke string konstanta yang berisi nama komputer jarak jauh tempat perangkat berada. Nilai NULL untuk MachineName menentukan bahwa perangkat diinstal pada komputer lokal. Komputer jarak jauh tidak didukung dimulai dengan Windows 8 dan Windows Server 2012.

Perhatian

Menggunakan fungsi ini untuk mengakses komputer jarak jauh tidak didukung dimulai dengan Windows 8 dan Windows Server 2012, karena fungsi ini telah dihapus.

Reserved

Dicadangkan untuk penggunaan internal. Parameter ini harus diatur ke NULL.

Nilai kembali

Jika operasi berhasil, SetupDiGetClassDevsEx mengembalikan handel ke kumpulan informasi perangkat yang berisi semua perangkat yang diinstal yang cocok dengan parameter yang disediakan. Jika operasi gagal, fungsi akan mengembalikan INVALID_HANDLE_VALUE. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Pemanggil SetupDiGetClassDevsEx harus menghapus informasi perangkat yang dikembalikan yang diatur ketika tidak lagi diperlukan dengan memanggil SetupDiDestroyDeviceInfoList.

Jika DeviceInfoSetadalah NULL, SetupDiGetClassDevsEx membuat kumpulan informasi perangkat baru yang berisi elemen informasi perangkat yang diambil dan mengembalikan handel ke kumpulan informasi perangkat baru. Jika pemanggil meminta agar fungsi mengambil perangkat untuk kelas penyiapan perangkat yang disediakan oleh parameter ClassGuid , fungsi mengatur kelas penyiapan perangkat dari informasi perangkat baru yang diatur ke GUID kelas yang disediakan.

Jika DeviceInfoSet tidak diatur ke NULL, fungsi menambahkan elemen informasi perangkat yang diambil ke kumpulan informasi perangkat yang terkait dengan handel yang disediakan, dan mengembalikan handel yang disediakan. Jika ClassGuid menyediakan kelas penyiapan perangkat, kelas penyiapan perangkat dari kumpulan informasi perangkat yang disediakan harus diatur ke GUID kelas yang disediakan.

Opsi Kontrol Kelas Penyetelan Perangkat

Gunakan opsi pemfilteran berikut untuk mengontrol apakah SetupDiGetClassDevsEx mengembalikan perangkat untuk semua kelas penyiapan perangkat atau hanya untuk kelas penyiapan perangkat tertentu:

Untuk mengembalikan perangkat untuk semua kelas penyiapan perangkat, atur bendera DIGCF_ALLCLASSES dan atur parameter ClassGuid ke NULL.
Untuk mengembalikan perangkat hanya untuk kelas penyiapan perangkat tertentu, jangan atur DIGCF_ALLCLASSES dan gunakan ClassGuid untuk menyediakan GUID kelas penyiapan perangkat.

Selain itu, Anda dapat menggunakan opsi pemfilteran berikut untuk membatasi lebih lanjut perangkat mana yang dikembalikan.

Untuk mengembalikan hanya perangkat yang ada dalam sistem, atur bendera DIGCF_PRESENT.
Untuk mengembalikan hanya perangkat yang merupakan bagian dari profil perangkat keras saat ini, atur bendera DIGCF_PROFILE.
Untuk mengembalikan perangkat hanya untuk enumerator PnP tertentu, gunakan parameter Enumerator untuk menyediakan GUID atau nama simbolis enumerator. Jika Enumerator adalah NULL, SetupDiGetClassDevsEx mengembalikan perangkat untuk semua enumerator PnP.

Opsi Kontrol Kelas Antarmuka Perangkat

Gunakan opsi pemfilteran berikut untuk mengontrol apakah SetupDiGetClassDevsEx mengembalikan perangkat yang mendukung kelas antarmuka perangkat apa pun atau hanya perangkat yang mendukung kelas antarmuka perangkat tertentu:

Untuk mengembalikan perangkat yang mendukung antarmuka perangkat dari kelas apa pun, atur bendera DIGCF_DEVICEINTERFACE, atur bendera DIGCF_ALLCLASSES, dan atur ClassGuid ke NULL. Fungsi ini menambahkan ke informasi perangkat yang mengatur elemen informasi perangkat yang mewakili perangkat tersebut, lalu menambahkan ke elemen informasi perangkat daftar antarmuka perangkat yang berisi semua antarmuka perangkat yang didukung perangkat.
Untuk mengembalikan hanya perangkat yang mendukung antarmuka perangkat dari kelas tertentu, atur bendera DIGCF_DEVICEINTERFACE dan gunakan parameter ClassGuid untuk menyediakan GUID kelas dari kelas antarmuka perangkat. Fungsi ini menambahkan ke informasi perangkat yang mengatur elemen informasi perangkat yang mewakili perangkat tersebut, lalu menambahkan antarmuka perangkat dari kelas yang ditentukan ke daftar antarmuka perangkat untuk elemen informasi perangkat tersebut.

Selain itu, Anda dapat menggunakan opsi pemfilteran berikut untuk mengontrol apakah SetupDiGetClassDevsEx hanya mengembalikan perangkat yang mendukung antarmuka default sistem untuk kelas antarmuka perangkat:

Untuk mengembalikan hanya perangkat yang mendukung antarmuka default sistem, jika satu diatur, untuk kelas antarmuka perangkat tertentu, atur bendera DIGCF_DEVICEINTERFACE, atur bendera DIGCF_DEFAULT, dan gunakan ClassGuid untuk menyediakan GUID kelas dari kelas antarmuka perangkat. Fungsi ini menambahkan ke informasi perangkat yang mengatur elemen informasi perangkat yang mewakili perangkat tersebut, lalu menambahkan antarmuka default sistem ke daftar antarmuka perangkat untuk elemen informasi perangkat tersebut.
Untuk mengembalikan perangkat yang mendukung antarmuka default sistem untuk kelas antarmuka perangkat yang tidak ditentukan, atur bendera DIGCF_DEVICEINTERFACE, atur bendera DIGCF_ALLCLASSES, atur bendera DIGCF_DEFAULT, dan atur ClassGuid ke NULL. Fungsi ini menambahkan ke informasi perangkat yang mengatur elemen informasi perangkat yang mewakili perangkat tersebut, lalu menambahkan antarmuka default sistem ke daftar antarmuka perangkat untuk elemen informasi perangkat tersebut.

Anda juga dapat menggunakan opsi berikut dalam kombinasi dengan opsi lain untuk membatasi lebih lanjut perangkat mana yang dikembalikan.

Untuk mengembalikan hanya perangkat yang ada dalam sistem, atur bendera DIGCF_PRESENT.
Untuk mengembalikan hanya perangkat yang merupakan bagian dari profil perangkat keras saat ini, atur bendera DIGCF_PROFILE.
Untuk mengembalikan hanya perangkat tertentu, atur bendera DIGCF_DEVICEINTERFACE dan gunakan parameter Enumerator untuk menyediakan ID instans perangkat perangkat. Untuk menyertakan semua perangkat yang mungkin, atur Enumerator ke NULL.

Mengambil Perangkat di Kelas Penyiapan Perangkat yang Mendukung Kelas Antarmuka Perangkat

Penginstal dapat menggunakan SetupDiGetClassDevsEx untuk mengambil daftar perangkat dari kelas penyiapan perangkat tertentu yang mendukung antarmuka perangkat dari kelas antarmuka perangkat tertentu. Misalnya, untuk mengambil daftar semua perangkat di komputer lokal yang mendukung antarmuka perangkat di kelas antarmuka "perangkat yang dipasang" dan yang merupakan anggota kelas penyiapan perangkat "Volume", alat penginstal harus melakukan operasi berikut:

Panggil SetupDiCreateDeviceInfoList untuk membuat informasi perangkat kosong yang ditetapkan untuk kelas penyiapan perangkat "Volume". Atur ClassGuid ke penunjuk ke GUID kelas untuk kelas penyiapan perangkat "Volume" dan atur hwndParent sebagaimana mewajibkan. Menanggapi panggilan seperti itu, fungsi akan mengembalikan handel untuk mengetik HDEVINFO ke kumpulan informasi perangkat.
Panggil SetupDiGetClassDevsEx dengan pengaturan berikut:
- Atur ClassGuid ke pointer ke GUID kelas kelas antarmuka perangkat "perangkat yang dipasang".
- Atur Bendera ke DIGCF_DEVICEINTERFACE.
- Atur DeviceInfoSet ke handel HDEVINFO yang diperoleh dalam langkah (1).
- Atur hwndParent yang sesuai dan parameter yang tersisa ke NULL.

Dalam operasi jenis ini, SetupDiGetClassDevsEx mengembalikan perangkat jika kelas penyiapan perangkat sama dengan set informasi perangkat yang disediakan dan jika perangkat mendukung antarmuka perangkat yang kelasnya sama dengan kelas antarmuka perangkat yang ditentukan.

Catatan

Header setupapi.h mendefinisikan SetupDiGetClassDevsEx 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	Tersedia di Microsoft Windows 2000 dan versi Windows yang lebih baru.
Target Platform	Desktop
Header	setupapi.h (termasuk Setupapi.h)
Pustaka	Setupapi.lib