Bagikan melalui

struktur SP_DEVINSTALL_PARAMS_A (setupapi.h)

  • Artikel

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_A {
  DWORD             cbSize;
  DWORD             Flags;
  DWORD             FlagsEx;
  HWND              hwndParent;
  PSP_FILE_CALLBACK InstallMsgHandler;
  PVOID             InstallMsgHandlerContext;
  HSPFILEQ          FileQueue;
  ULONG_PTR         ClassInstallReserved;
  DWORD             Reserved;
  CHAR              DriverPath[MAX_PATH];
} SP_DEVINSTALL_PARAMS_A, *PSP_DEVINSTALL_PARAMS_A;

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 penginstalan 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 ketika 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_Ex CM_Setup_DevNode CM_Query_And_Remove_SubTree_Ex CM_Setup_DevNode CM_Setup_DevNode_Ex CM_Set_HW_Prof_Flags CM_Set_HW_Prof_Flags_Ex CM_Enable_DevNode CM_Set_HW_Prof_Flags_Ex CM_Enable_DevNode_Ex CM_Enable_DevNode_Ex CM_Enable_DevNode_Ex CM_Disable_DevNodeCM_Disable_DevNode_Ex

DI_ENUMSINGLEINF

Atur apakah 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 ke menunjukkan bahwa halaman Pilih Perangkat harus mencantumkan driver dalam urutan muncul dalam file INF, alih-alih mengurutkannya menurut abjad.

DI_INSTALLDISABLED

Atur apakah perangkat harus diinstal dalam status dinonaktifkan 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. Antrean File.

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 root.

Bendera ini mengambil alih 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 usang:

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 penginstalan 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 root.

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 membangun 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 inklusi 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 yang Harus 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 tak bisa menjamin bahwa ia bisa mengambil berkas pengandar lagi 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 alat penginstal untuk memberi tahu mereka bahwa sesuatu telah berubah.

DI_FLAGSEX_RECURSIVESEARCH

(Windows Vista dan yang lebih baru.) Jika diatur, saat 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 untuk 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 dikommpilasikan 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 pengandar yang mencakup semua pengandar yang tercantum dalam file INF dari kelas penyetelan yang ditentukan. Jika kelas penyiapan yang ditentukan ADALAH NULL karena set atau perangkat HDEVINFO tidak memiliki kelas terkait, daftar ini mencakup 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 usang:

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 Anda 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 dilakukan.

ClassInstallReserved

Pointer 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)

Lihat juga

SetupDiBuildClassInfoList

SetupDiBuildDriverInfoList

SetupDiCallClassInstaller

SetupDiGetDeviceInstallParams

SetupDiInstallDevice

SetupDiSelectDevice

SetupDiSetDeviceInstallParams