Fungsi SetupDiGetClassDevsW (setupapi.h)

  • Artikel

Fungsi SetupDiGetClassDevs mengembalikan handel ke kumpulan informasi perangkat yang berisi elemen informasi perangkat yang diminta untuk komputer lokal.

Sintaks

WINSETUPAPI HDEVINFO SetupDiGetClassDevsW(
  [in, optional] const GUID *ClassGuid,
  [in, optional] PCWSTR     Enumerator,
  [in, optional] HWND       hwndParent,
  [in]           DWORD      Flags
);

Parameter

[in, optional] ClassGuid

Pointer ke GUID untuk kelas penyiapan perangkat atau kelas antarmuka perangkat. Penunjuk ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya tentang cara mengatur 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) nilai atau nama simbolis. Misalnya, "PCI" dapat digunakan untuk menentukan nilai PnP PCI. Contoh lain dari nama simbolis untuk nilai 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 enumerasi 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 di 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 OR dari nol atau lebih dari bendera berikut. Untuk informasi selengkapnya tentang menggabungkan bendera ini, lihat bagian Keterangan berikut.

DIGCF_ALLCLASSES

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

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 satu diatur, untuk kelas antarmuka perangkat yang ditentukan.

DIGCF_PRESENT

Mengembalikan hanya perangkat yang saat ini ada dalam sistem.

DIGCF_PROFILE

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

Nilai kembali

Jika operasi berhasil, SetupDiGetClassDevs 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 SetupDiGetClassDevs harus menghapus informasi perangkat yang dikembalikan yang diatur ketika tidak lagi diperlukan dengan memanggil SetupDiDestroyDeviceInfoList.

Panggil SetupDiGetClassDevsEx untuk mengambil perangkat untuk kelas di komputer jarak jauh.

Opsi Kontrol Kelas Penyetelan Perangkat

Gunakan opsi pemfilteran berikut untuk mengontrol apakah SetupDiGetClassDevs 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 dalam kombinasi satu sama 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 perangkat hanya untuk enumerator PnP tertentu, gunakan parameter Enumerator untuk menyediakan GUID atau nama simbolis enumerator. Jika EnumeratorADALAH NULL, SetupDiGetClassDevs mengembalikan perangkat untuk semua enumerator PnP.

Opsi Kontrol Kelas Antarmuka Perangkat

Gunakan opsi pemfilteran berikut untuk mengontrol apakah SetupDiGetClassDevs 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 dan kemudian 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 SetupDiGetClassDevs 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.

Contoh

Berikut ini adalah beberapa contoh cara menggunakan fungsi SetupDiGetClassDevs .

Contoh 1: Buat daftar semua perangkat dalam sistem, termasuk perangkat yang saat ini tidak ada.

Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES);

Contoh 2: Buat daftar semua perangkat yang ada dalam sistem.

Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES | DIGCF_PRESENT);

Contoh 3: Buat daftar semua perangkat yang ada dalam sistem yang berasal dari kelas penyiapan perangkat adaptor jaringan.

Handle = SetupDiGetClassDevs(&GUID_DEVCLASS_NET, NULL, NULL, DIGCF_PRESENT);

Contoh 4: Buat daftar semua perangkat yang ada dalam sistem yang telah mengaktifkan antarmuka dari kelas antarmuka perangkat volume penyimpanan.

Handle = SetupDiGetClassDevs(&GUID_DEVINTERFACE_VOLUME, NULL, NULL, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);

Contoh 5: Buat daftar semua perangkat yang ada dalam sistem tetapi bukan milik kelas penyiapan perangkat yang diketahui (Windows Vista dan versi Windows yang lebih baru).

Catatan Anda tidak dapat mengatur parameter ClassGuid ke GUID_DEVCLASS_UNKNOWN untuk mendeteksi perangkat dengan kelas penyiapan yang tidak diketahui. Sebagai gantinya, Anda harus mengikuti contoh ini.
 
DeviceInfoSet = SetupDiGetClassDevs(
                                    NULL,
                                    NULL,
                                    NULL,
                                    DIGCF_ALLCLASSES | DIGCF_PRESENT);

ZeroMemory(&DeviceInfoData, sizeof(SP_DEVINFO_DATA));
DeviceInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
DeviceIndex = 0;
    
while (SetupDiEnumDeviceInfo(
                             DeviceInfoSet,
                             DeviceIndex,
                             &DeviceInfoData)) {
    DeviceIndex++;

    if (!SetupDiGetDeviceProperty(
                                  DeviceInfoSet,
                                  &DeviceInfoData,
                                  &DEVPKEY_Device_Class,
                                  &PropType,
                                  (PBYTE)&DevGuid,
                                  sizeof(GUID),
                                  &Size,
                                  0) || PropType != DEVPROP_TYPE_GUID) {

        Error = GetLastError();

        if (Error == ERROR_NOT_FOUND) {
            \\
            \\ This device has an unknown device setup class.
            \\
            }
        }                 
    }

if (DeviceInfoSet) {
    SetupDiDestroyDeviceInfoList(DeviceInfoSet);
    }

Catatan

Header setupapi.h mendefinisikan SetupDiGetClassDevs sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praproscesor 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 DesktopUntuk universal, panggil CM_Get_Device_ID_ListFor universal, panggil CM_Get_Device_Interface_List
Header setupapi.h (termasuk SetupAPI.h)
Pustaka SetupAPI.lib
DLL SetupAPI.dll
Set API ext-ms-win-setupapi-classinstallers-l1-1-0 (diperkenalkan dalam Windows 8)

Lihat juga

Set Informasi Perangkat

ID Instans Perangkat

SetupDiCreateDeviceInfoList

SetupDiDestroyDeviceInfoList

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevsEx