SetupDiGetCustomDevicePropertyA (setupapi.h)

Artikel
03/04/2024

Fungsi SetupDiGetCustomDeviceProperty mengambil properti perangkat kustom tertentu dari registri.

Sintaks

WINSETUPAPI BOOL SetupDiGetCustomDevicePropertyA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            PCSTR            CustomPropertyName,
  [in]            DWORD            Flags,
  [out, optional] PDWORD           PropertyRegDataType,
  [out]           PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize
);

Parameter

[in] DeviceInfoSet

Handel ke kumpulan informasi perangkat yang berisi elemen informasi perangkat yang mewakili perangkat untuk mengambil properti perangkat kustom.

[in] DeviceInfoData

Penunjuk ke struktur SP_DEVINFO_DATA yang menentukan elemen informasi perangkat di DeviceInfoSet.

[in] CustomPropertyName

Nama nilai registri yang mewakili properti kustom.

[in] Flags

Nilai bendera yang menunjukkan bagaimana informasi yang diminta harus dikembalikan. Bendera bisa nol atau salah satu dari berikut ini:

DICUSTOMDEVPROP_MERGE_MULTISZ

Jika diatur, fungsi mengambil nilai properti khusus instans perangkat dan nilai properti khusus ID perangkat keras, yang digabungkan sebagai string yang REG_MULTI_SZ ketik. (Untuk informasi selengkapnya, lihat bagian Keterangan pada halaman referensi ini.)

[out, optional] PropertyRegDataType

Penunjuk ke variabel jenis DWORD yang menerima jenis data properti yang diambil. Jenis data ditentukan sebagai salah satu konstanta awalan REG_ yang mewakili jenis data registri. Parameter ini bersifat opsional dan dapat berupa NULL.

[out] PropertyBuffer

Penunjuk ke buffer yang menerima informasi properti yang diminta.

[in] PropertyBufferSize

Ukuran, dalam byte, dari buffer PropertyBuffer .

[out, optional] RequiredSize

Penunjuk ke variabel jenis DWORD yang menerima ukuran buffer, dalam byte, yang diperlukan untuk menerima informasi yang diminta. Parameter ini bersifat opsional dan dapat berupa NULL. Jika parameter ini ditentukan, SetupDiGetCustomDeviceProperty mengembalikan ukuran yang diperlukan, terlepas dari apakah buffer PropertyBuffer cukup besar untuk menerima informasi yang diminta.

Nilai kembali

Jika operasi berhasil, SetupDiGetCustomDeviceProperty mengembalikan TRUE. Jika tidak, fungsi mengembalikan FALSE dan kesalahan yang dicatat dapat diambil dengan panggilan ke GetLastError. Jika buffer PropertyBuffer tidak cukup besar untuk menerima informasi yang diminta, SetupDiGetCustomDeviceProperty mengembalikan FALSE dan panggilan berikutnya ke GetLastError akan mengembalikan ERROR_INSUFFICIENT_BUFFER.

Keterangan

SetupDiGetCustomDeviceProperty mengambil properti perangkat yang terkait dengan satu instans perangkat atau dengan semua perangkat yang cocok dengan ID perangkat keras tertentu. (Untuk informasi tentang ID perangkat keras, lihat String Identifikasi Perangkat).

Vendor dapat mengatur properti untuk instans perangkat dengan menggunakan arahan INF AddReg di bagian INF DDInstall.HW dan menentukan akar registri HKR .

Hanya sistem yang dapat mengatur properti untuk ID perangkat keras. Sistem memasok properti "Ikon" untuk beberapa ID perangkat keras.

Fungsi pertama-tama memeriksa untuk melihat apakah properti yang ditentukan ada untuk instans perangkat yang ditentukan. Jika demikian, nilai properti dikembalikan. Jika tidak, fungsi memeriksa untuk melihat apakah properti ada untuk semua perangkat yang cocok dengan ID perangkat keras dari instans perangkat yang ditentukan. Jika demikian, nilai properti dikembalikan. Jika DICUSTOMDEVPROP_MERGE_MULTISZ diatur dalam Bendera, fungsi mengembalikan nilai properti yang terkait dengan instans perangkat dan ID perangkat keras, jika keduanya ada.

Catatan

Header setupapi.h mendefinisikan SetupDiGetCustomDeviceProperty 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 Windows XP dan versi Windows yang lebih baru.
Target Platform	Desktop
Header	setupapi.h (termasuk Setupapi.h)
Pustaka	Setupapi.lib
DLL	Setupapi.dll