struktur SP_DEVINSTALL_PARAMS_W (setupapi.h)
Struktur SP_DEVINSTALL_PARAMS berisi parameter penginstalan perangkat yang terkait dengan elemen informasi perangkat tertentu atau terkait secara global dengan kumpulan informasi perangkat.
Sintaks
typedef struct _SP_DEVINSTALL_PARAMS_W {
DWORD cbSize;
DWORD Flags;
DWORD FlagsEx;
HWND hwndParent;
PSP_FILE_CALLBACK InstallMsgHandler;
PVOID InstallMsgHandlerContext;
HSPFILEQ FileQueue;
ULONG_PTR ClassInstallReserved;
DWORD Reserved;
WCHAR DriverPath[MAX_PATH];
} SP_DEVINSTALL_PARAMS_W, *PSP_DEVINSTALL_PARAMS_W;
Anggota
cbSize
Ukuran, dalam byte, dari struktur SP_DEVINSTALL_PARAMS.
Flags
Bendera yang mengontrol penginstalan dan operasi antarmuka pengguna. Beberapa bendera dapat diatur sebelum mengirim permintaan penginstalan perangkat sementara bendera lain diatur secara otomatis selama pemrosesan beberapa permintaan. Bendera bisa menjadi kombinasi dari nilai berikut.
Nilai bendera tercantum dalam grup: dapat ditulis oleh aplikasi dan alat penginstal penginstal perangkat , baca-saja (hanya diatur oleh OS), dicadangkan, dan usang. Grup pertama mencantumkan bendera yang dapat ditulis:
DI_CLASSINSTALLPARAMS
Atur untuk menggunakan parameter Penginstalan Kelas. SetupDiSetClassInstallParams mengatur bendera ini saat pemanggil menentukan parameter dan menghapus bendera saat pemanggil menentukan penunjuk parameter NULL .
DI_COMPAT_FROM_CLASS
Atur untuk memaksa SetupDiBuildDriverInfoList untuk membuat daftar driver yang kompatibel dari daftar driver kelasnya, bukan file INF.
DI_DRIVERPAGE_ADDED
Diatur oleh penginstal kelas atau penginstal bersama jika alat penginstal menyediakan halaman yang menggantikan halaman properti driver yang disediakan sistem. Jika bendera ini diatur, sistem operasi tidak menampilkan halaman driver yang disediakan sistem.
DI_DONOTCALLCONFIGMG
Atur jika manajer konfigurasi tidak boleh dipanggil untuk menghapus atau menghitung ulang perangkat selama eksekusi fungsi penginstalan perangkat tertentu (misalnya, SetupDiInstallDevice).
Jika bendera ini diatur, aplikasi penginstalan perangkat, penginstal kelas, dan penginstal bersama tidak boleh memanggil fungsi berikut:
CM_Reenumerate_DevNodeCM_Query_And_Remove_SubTree CM_Reenumerate_DevNode CM_Reenumerate_DevNode_Ex CM_Setup_DevNode CM_Query_And_Remove_SubTree_Ex CM_Setup_DevNode CM_Setup_DevNode_Ex CM_Set_HW_Prof_Flags_Ex CM_Set_HW_Prof_Flags_Ex CM_Enable_DevNodeCM_Set_HW_Prof_Flags CM_Enable_DevNode_Ex CM_Enable_DevNode_Ex CM_Setup_DevNode CM_Enable_DevNode_Ex CM_Disable_DevNode CM_Set_HW_Prof_Flags_Ex CM_Disable_DevNode_Ex
DI_ENUMSINGLEINF
Atur jika penginstal dan komponen penginstalan perangkat lainnya hanya boleh mencari file INF yang ditentukan oleh SP_DEVINSTALL_PARAMS. DriverPath. Jika bendera ini diatur, DriverPath berisi jalur satu file INF alih-alih jalur direktori.
DI_INF_IS_SORTED
Atur untuk menunjukkan bahwa halaman Pilih Perangkat harus mencantumkan driver dalam urutan munculnya dalam file INF, alih-alih mengurutkannya menurut abjad.
DI_INSTALLDISABLED
Atur apakah perangkat harus diinstal dalam keadaan nonaktif secara default. Agar dikenali, bendera ini harus diatur sebelum Windows memanggil handler default untuk permintaan DIF_INSTALLDEVICE .
DI_NEEDREBOOT
Untuk sistem operasi berbasis NT, bendera ini diatur jika perangkat mengharuskan komputer dimulai ulang setelah penginstalan perangkat atau status perangkat berubah. Penginstal kelas atau penginstal bersama dapat mengatur bendera ini kapan saja selama penginstalan perangkat, jika alat penginstal menentukan bahwa mulai ulang diperlukan.
DI_NEEDRESTART
Sama seperti DI_NEEDREBOOT.
DI_NOBROWSE
Atur untuk menonaktifkan penjelajahan saat pengguna memilih jalur disk OEM. Aplikasi penginstalan perangkat mengatur bendera ini untuk membatasi pengguna hanya menginstal dari lokasi media penginstalan.
DI_NODI_DEFAULTACTION
Atur jika SetupDiCallClassInstaller tidak boleh melakukan tindakan default jika penginstal kelas mengembalikan ERR_DI_DO_DEFAULT atau tidak ada penginstal kelas.
DI_NOFILECOPY
Atur apakah aplikasi dan komponen penginstalan perangkat, seperti SetupDiInstallDevice, harus melewati penyalinan file.
DI_NOVCP
Atur untuk menonaktifkan pembuatan antrean salinan baru. Gunakan antrean salinan yang disediakan penelepon di SP_DEVINSTALL_PARAMS. FileQueue.
DI_NOWRITE_IDS
Atur untuk mencegah SetupDiInstallDevice menulis ID perangkat keras yang ditentukan INF dan ID yang kompatibel ke properti perangkat untuk simpul perangkat (devnode). Bendera ini hanya boleh diatur untuk perangkat yang dijumlahkan akar.
Bendera ini menggantikan bendera DI_FLAGSEX_ALWAYSWRITEIDS.
DI_PROPERTIES_CHANGE
Diatur oleh Manajer Perangkat jika properti perangkat diubah, yang memerlukan pembaruan antarmuka pengguna penginstal.
DI_QUIETINSTALL
Atur jika fungsi alat penginstal perangkat harus diam dan gunakan pilihan default sedapat mungkin. Penginstal kelas dan penginstal bersama tidak boleh menampilkan UI apa pun jika bendera ini diatur.
DI_RESOURCEPAGE_ADDED
Diatur oleh penginstal kelas atau penginstal bersama jika alat penginstal menyediakan halaman yang menggantikan halaman properti sumber daya yang disediakan sistem. Jika bendera ini diatur, sistem operasi tidak menampilkan halaman sumber daya yang disediakan sistem.
DI_SHOWOEM
Atur untuk mengizinkan dukungan untuk disk OEM. Jika bendera ini diatur, sistem operasi menyajikan tombol "Miliki Disk" di halaman Pilih Perangkat. Bendera ini diatur, secara default, dalam wizard yang disediakan sistem.
DI_USECI_SELECTSTRINGS
Atur apakah penginstal kelas atau string yang disediakan penginstal bersama yang harus digunakan selama SetupDiSelectDevice.
Bendera berikut bersifat baca-saja (hanya diatur oleh OS):
DI_DIDCLASS
Atur jika SetupDiBuildDriverInfoList telah membuat daftar driver untuk kelas perangkat ini. Jika daftar ini telah dibuat, daftar ini berisi semua informasi driver dan bendera ini selalu diatur. SetupDiDestroyDriverInfoList menghapus bendera ini saat menghapus daftar driver untuk kelas.
Bendera ini bersifat baca-saja. Hanya sistem operasi yang mengatur bendera ini.
DI_DIDCOMPAT
Atur jika SetupDiBuildDriverInfoList telah membuat daftar driver yang kompatibel untuk perangkat ini. Jika daftar ini telah dibuat, daftar ini berisi semua informasi driver dan bendera ini selalu diatur. SetupDiDestroyDriverInfoList menghapus bendera ini saat menghapus daftar driver yang kompatibel.
Bendera ini hanya diatur dalam parameter penginstalan perangkat yang terkait dengan elemen informasi perangkat tertentu, bukan dalam parameter untuk informasi perangkat yang ditetapkan secara keseluruhan.
Bendera ini bersifat baca-saja. Hanya sistem operasi yang mengatur bendera ini.
DI_MULTMFGS
Diatur oleh SetupDiBuildDriverInfoList jika daftar driver untuk kelas penyiapan perangkat berisi driver yang disediakan oleh beberapa produsen.
Bendera ini bersifat baca-saja. Hanya sistem operasi yang mengatur bendera ini.
Bendera berikut dicadangkan:
DI_AUTOASSIGNRES
DI_DISABLED
DI_FORCECOPY
DI_GENERALPAGE_ADDED
DI_OVERRIDE_INFFLAGS
DI_SHOWALL
DI_SHOWCLASS
DI_SHOWCOMPAT
Bendera berikut kedaluarsa:
DI_NOSELECTICONS
DI_PROPS_NOCHANGEUSAGE
FlagsEx
Bendera tambahan yang memberikan kontrol atas penginstalan dan operasi antarmuka pengguna. Beberapa bendera dapat diatur sebelum memanggil fungsi alat penginstal perangkat sementara bendera lain diatur secara otomatis selama pemrosesan beberapa fungsi. FlagsEx bisa menjadi kombinasi dari nilai berikut.
Nilai bendera tercantum dalam grup: dapat ditulis oleh aplikasi dan alat penginstal penginstal perangkat, baca-saja (hanya diatur oleh OS), dicadangkan, dan usang.
Grup pertama mencantumkan bendera yang dapat ditulis:
DI_FLAGSEX_ALLOWEXCLUDEDDRVS
Jika diatur, sertakan driver yang ditandai "Kecualikan Dari Pilih."
Misalnya, jika bendera ini diatur, SetupDiSelectDevice menampilkan driver yang memiliki status Kecualikan Dari Pilih dan SetupDiBuildDriverInfoList menyertakan Kecualikan Dari Pilih driver dalam daftar driver yang diminta.
Driver adalah "Kecualikan Dari Pilih" jika ditandai ExcludeFromSelect dalam file INF atau itu adalah driver untuk perangkat yang seluruh kelas pengaturannya ditandai NoInstallClass atau NoUseClass di INF penginstal kelas. Driver untuk perangkat PnP biasanya "Kecualikan Dari Pilih"; Perangkat PnP tidak boleh diinstal secara manual. Untuk membuat daftar file driver untuk perangkat PnP, pemanggil SetupDiBuildDriverInfoList harus mengatur bendera ini.
DI_FLAGSEX_ALWAYSWRITEIDS
Jika diatur dan bendera DI_NOWRITE_IDS jelas, selalu tulis perangkat keras dan ID yang kompatibel ke properti perangkat untuk devnode. Bendera ini hanya boleh diatur untuk perangkat yang dijumlahkan akar.
DI_FLAGSEX_APPENDDRIVERLIST
Jika diatur, SetupDiBuildDriverInfoList menambahkan daftar driver baru ke daftar yang sudah ada. Bendera ini relevan saat mencari beberapa lokasi.
DI_FLAGSEX_DRIVERLIST_FROM_URL
Jika diatur, buat daftar driver dari INF yang diambil dari URL yang ditentukan dalam SP_DEVINSTALL_PARAMS. DriverPath. Jika DriverPath adalah string kosong, gunakan situs web Windows Update.
Saat ini, sistem operasi tidak mendukung URL. Gunakan bendera ini untuk mengarahkan SetupDiBuildDriverInfoList untuk mencari situs web Windows Update.
Jangan atur bendera ini jika DI_QUIETINSTALL diatur.
DI_FLAGSEX_EXCLUDE_OLD_INET_DRIVERS
Jika diatur, jangan sertakan driver Internet lama saat membuat daftar driver. Bendera ini harus diatur kapan saja Anda membuat daftar driver potensial untuk perangkat. Anda dapat menghapus bendera ini jika Anda hanya mendapatkan daftar driver yang saat ini diinstal untuk perangkat.
DI_FLAGSEX_FILTERCLASSES
Jika diatur, SetupDiBuildClassInfoList akan memeriksa filter penyertaan kelas. Ini berarti bahwa perangkat tidak akan disertakan dalam daftar kelas jika kelasnya ditandai sebagai NoInstallClass.
DI_FLAGSEX_FILTERSIMILARDRIVERS
(Windows XP dan yang lebih baru.) Jika diatur, SetupDiBuildDriverInfoList menyertakan driver "serupa" saat membuat daftar driver kelas. Driver "serupa" adalah salah satu ID perangkat keras atau ID yang kompatibel dalam file INF sebagian (atau sepenuhnya) yang cocok dengan salah satu ID perangkat keras atau ID perangkat keras yang kompatibel.
DI_FLAGSEX_FINISHINSTALL_ACTION
(Windows Vista dan yang lebih baru.) Lihat Menandai Perangkat sebagai memiliki Tindakan Finish-Install untuk Dilakukan untuk informasi selengkapnya.
DI_FLAGSEX_INET_DRIVER
Jika disetel, driver diperoleh dari Internet. Windows tidak akan menggunakan INF peranti untuk menginstal perangkat di masa mendatang karena Windows tidak bisa menjamin bahwa ia bisa mengambil kembali berkas pengandar dari Internet.
DI_FLAGSEX_INSTALLEDDRIVER
(Windows XP dan yang lebih baru.) Jika diatur, SetupDiBuildDriverInfoList hanya menyertakan driver yang saat ini diinstal saat membuat daftar driver kelas atau driver yang kompatibel dengan perangkat.
DI_FLAGSEX_NO_CLASSLIST_NODE_MERGE
(Windows XP dan yang lebih baru.) Jika diatur, saat membuat daftar driver kelas, SetupDiBuildDriverInfoList tidak akan menggabungkan simpul dalam daftar driver yang berasal dari INF yang sama dan memiliki deskripsi dan peringkat driver yang sama.
DI_FLAGSEX_NO_DRVREG_MODIFY
Jangan memproses entri AddReg dan DelReg untuk kunci perangkat keras dan perangkat lunak (driver) perangkat. Artinya, entri AddReg dan DelReg dalam file INF DDInstall dan DDInstall. Bagian HW .
DI_FLAGSEX_POWERPAGE_ADDED
Jika diatur, alat penginstal menambahkan halaman mereka sendiri untuk dialog properti daya. Sistem operasi tidak akan menampilkan halaman properti daya yang disediakan sistem. Bendera ini hanya relevan jika perangkat mendukung manajemen daya.
DI_FLAGSEX_PROPCHANGE_PENDING
Jika diatur, pengguna membuat perubahan pada satu atau beberapa lembar properti perangkat. Penyedia halaman properti biasanya mengatur bendera ini.
Saat pengguna menutup lembar properti perangkat, Manajer Perangkat memeriksa bendera DI_FLAGSEX_PROPCHANGE_PENDING. Jika diatur, Manajer Perangkat menghapus bendera ini, mengatur bendera DI_PROPERTIES_CHANGE, dan mengirim permintaan DIF_PROPERTYCHANGE ke penginstal untuk memberi tahu mereka bahwa ada sesuatu yang telah berubah.
DI_FLAGSEX_RECURSIVESEARCH
(Windows Vista dan yang lebih baru.) Jika diatur, ketika SetupDiBuildDriverInfoList mencari INF di jalur yang ditentukan dalam nilai DriverPath , pencarian akan rekursif.
DI_FLAGSEX_SEARCH_PUBLISHED_INFS
(Windows Vista dan yang lebih baru.) Jika diatur, ketika SetupDiBuildDriverInfoList digunakan untuk mencari INF tanpa jalur INF atau jalur pencarian yang ditentukan, ini membatasi pencarian hanya ke INF yang telah diimpor ke Penyimpanan Driver.
DI_FLAGSEX_SETFAILEDINSTALL
Atur jika penginstalan gagal. Jika bendera ini diatur, fungsi SetupDiInstallDevice hanya mengatur bendera FAILEDINSTALL di nilai registri ConfigFlags perangkat. Jika DI_FLAGSEX_SETFAILEDINSTALL diatur, penginstal bersama harus mengembalikan NO_ERROR sebagai respons terhadap DIF_INSTALLDEVICE, sementara penginstal kelas harus mengembalikan NO_ERROR atau ERROR_DI_DO_DEFAULT.
DI_FLAGSEX_USECLASSFORCOMPAT
Filter file INF pada kelas penyiapan perangkat saat membuat daftar driver yang kompatibel. Jika kelas penyiapan perangkat diketahui, mengatur bendera ini mengurangi waktu yang diperlukan untuk membuat daftar driver yang kompatibel saat mencari file INF yang tidak dikompresi sebelumnya. Bendera ini diabaikan jika DI_COMPAT_FROM_CLASS diatur.
Bendera berikut bersifat baca-saja; hanya sistem operasi yang menetapkan bendera ini:
DI_FLAGSEX_CI_FAILED
Diatur oleh sistem operasi jika penginstal kelas gagal dimuat atau dimulai. Bendera ini bersifat baca-saja.
DI_FLAGSEX_DIDCOMPATINFO
Windows telah membuat daftar simpul pengandar yang kompatibel dengan perangkat. Bendera ini bersifat baca-saja.
DI_FLAGSEX_DIDINFOLIST
Windows telah membuat daftar simpul driver yang mencakup semua driver yang tercantum dalam file INF dari kelas penyetelan yang ditentukan. Jika kelas penyiapan yang ditentukan adalah NULL karena set HDEVINFO atau perangkat tidak memiliki kelas terkait, daftar menyertakan semua simpul driver dari semua file INF yang tersedia. Bendera ini bersifat baca-saja.
DI_FLAGSEX_IN_SYSTEM_SETUP
Jika diatur, penginstalan terjadi selama penyiapan sistem awal. Bendera ini bersifat baca-saja.
Bendera berikut dicadangkan dan tidak boleh digunakan:
DI_FLAGSEX_ALTPLATFORM_DRVSEARCH
DI_FLAGSEX_BACKUPONREPLACE
DI_FLAGSEX_DEVICECHANGE
DI_FLAGSEX_OLDINF_IN_CLASSLIST
DI_FLAGSEX_PREINSTALLBACKUP
DI_FLAGSEX_RESTART_DEVICE_ONLY
DI_FLAGSEX_USEOLDINFSEARCH
Bendera berikut kedaluarsa:
DI_FLAGSEX_AUTOSELECTRANK0
DI_FLAGSEX_NOUIONQUERYREMOVE
hwndParent
Handel jendela yang akan memiliki dialog antarmuka pengguna yang terkait dengan perangkat ini.
InstallMsgHandler
Panggilan balik yang digunakan untuk menangani peristiwa selama penyalinan file. Alat penginstal dapat menggunakan panggilan balik, misalnya, untuk melakukan pemrosesan khusus saat melakukan antrean file.
InstallMsgHandlerContext
Data privat yang digunakan oleh panggilan balik InstallMsgHandler .
FileQueue
Handel ke antrean file yang disediakan penelepon di mana operasi file harus diantrekan tetapi tidak dilakukan.
Jika Anda mengaitkan antrean file dengan kumpulan informasi perangkat (SetupDiSetDeviceInstallParams), Anda harus memisahkan antrean dari informasi perangkat yang ditetapkan sebelum menghapus kumpulan informasi perangkat. Jika Anda gagal memisahkan antrean file, Windows tidak dapat mengurangi jumlah referensinya pada set informasi perangkat dan tidak dapat membebaskan memori.
Antrean ini hanya digunakan jika bendera DI_NOVCP diatur, menunjukkan bahwa operasi file harus diantrekan tetapi tidak diterapkan.
ClassInstallReserved
Penunjuk untuk data penginstal kelas. Penginstal bersama tidak boleh menggunakan bidang ini.
Reserved
Dicadangkan. Hanya untuk penggunaan internal.
DriverPath[MAX_PATH]
Jalur ini digunakan oleh fungsi SetupDiBuildDriverInfoList .
Keterangan
Catatan
Header setupapi.h mendefinisikan SP_DEVINSTALL_PARAMS 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 |
|---|---|
| Header | setupapi.h (termasuk Setupapi.h) |