Fungsi SetupDiGetDeviceInterfaceDetailW (setupapi.h)

Artikel
03/15/2023

Fungsi SetupDiGetDeviceInterfaceDetail mengembalikan detail tentang antarmuka perangkat.

Sintaks

WINSETUPAPI BOOL SetupDiGetDeviceInterfaceDetailW(
  [in]            HDEVINFO                           DeviceInfoSet,
  [in]            PSP_DEVICE_INTERFACE_DATA          DeviceInterfaceData,
  [out, optional] PSP_DEVICE_INTERFACE_DETAIL_DATA_W DeviceInterfaceDetailData,
  [in]            DWORD                              DeviceInterfaceDetailDataSize,
  [out, optional] PDWORD                             RequiredSize,
  [out, optional] PSP_DEVINFO_DATA                   DeviceInfoData
);

Parameter

[in] DeviceInfoSet

Penunjuk ke kumpulan informasi perangkat yang berisi antarmuka untuk mengambil detailnya. Handel ini biasanya dikembalikan oleh SetupDiGetClassDevs.

[in] DeviceInterfaceData

Penunjuk ke struktur SP_DEVICE_INTERFACE_DATA yang menentukan antarmuka di DeviceInfoSet untuk mengambil detailnya. Pointer jenis ini biasanya dikembalikan oleh SetupDiEnumDeviceInterfaces.

[out, optional] DeviceInterfaceDetailData

Penunjuk ke struktur SP_DEVICE_INTERFACE_DETAIL_DATA untuk menerima informasi tentang antarmuka yang ditentukan. Parameter ini bersifat opsional dan dapat berupa NULL. Parameter ini harus NULL jika DeviceInterfaceDetailSize adalah nol. Jika parameter ini ditentukan, pemanggil harus mengatur DeviceInterfaceDetailData.cbSize ke sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA) sebelum memanggil fungsi ini. Anggota cbSize selalu berisi ukuran bagian tetap dari struktur data, bukan ukuran yang mencerminkan string panjang variabel di akhir.

[in] DeviceInterfaceDetailDataSize

Ukuran buffer DeviceInterfaceDetailData . Buffer harus setidaknya (offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + sizeof(TCHAR)) byte, untuk berisi bagian tetap dari struktur dan satu NULL untuk mengakhiri string MULTI_SZ kosong.

Parameter ini harus nol jika DeviceInterfaceDetailData adalah NULL.

[out, optional] RequiredSize

Penunjuk ke variabel jenis DWORD yang menerima ukuran buffer DeviceInterfaceDetailData yang diperlukan. Ukuran ini mencakup ukuran bagian tetap dari struktur ditambah jumlah byte yang diperlukan untuk string jalur perangkat dengan panjang variabel. Parameter ini bersifat opsional dan dapat berupa NULL.

[out, optional] DeviceInfoData

Penunjuk ke buffer yang menerima informasi tentang perangkat yang mendukung antarmuka yang diminta. Pemanggil harus mengatur DeviceInfoData.cbSize ke sizeof(SP_DEVINFO_DATA). Parameter ini bersifat opsional dan dapat berupa NULL.

Mengembalikan nilai

SetupDiGetDeviceInterfaceDetail mengembalikan TRUE jika fungsi selesai tanpa kesalahan. Jika fungsi selesai dengan kesalahan, FALSE dikembalikan dan kode kesalahan untuk kegagalan dapat diambil dengan memanggil GetLastError.

Keterangan

Menggunakan fungsi ini untuk mendapatkan detail tentang antarmuka biasanya merupakan proses dua langkah:

Dapatkan ukuran buffer yang diperlukan. Panggil SetupDiGetDeviceInterfaceDetail dengan pointer NULLDeviceInterfaceDetailData , DeviceInterfaceDetailDataSize nol, dan variabel RequiredSize yang valid. Menanggapi panggilan seperti itu, fungsi ini mengembalikan ukuran buffer yang diperlukan di RequiredSize dan gagal dengan GetLastError mengembalikan ERROR_INSUFFICIENT_BUFFER.
Alokasikan buffer berukuran tepat dan panggil fungsi lagi untuk mendapatkan detail antarmuka.

Detail antarmuka yang dikembalikan oleh fungsi ini terdiri dari jalur perangkat yang dapat diteruskan ke fungsi Win32 seperti CreateFile. Jangan mencoba mengurai nama simbolis jalur perangkat. Jalur perangkat dapat digunakan kembali di seluruh sistem dimulai.

SetupDiGetDeviceInterfaceDetail dapat digunakan hanya untuk mendapatkan DeviceInfoData. Jika antarmuka ada tetapi DeviceInterfaceDetailData adalah NULL, fungsi ini gagal, GetLastError mengembalikan ERROR_INSUFFICIENT_BUFFER, dan struktur DeviceInfoData diisi dengan informasi tentang perangkat yang mengekspos antarmuka.

Catatan

Header setupapi.h mendefinisikan SetupDiGetDeviceInterfaceDetail sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preproscessor 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
Set API	ext-ms-win-setupapi-classinstallers-l1-1-2 (diperkenalkan dalam Windows 10, versi 10.0.14393)

Lihat juga

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs

Bagikan melalui