DIF_SELECTDEVICE

Artikel
06/15/2023

Permintaan DIF_SELECTDEVICE memungkinkan alat penginstal untuk berpartisipasi dalam memilih driver untuk perangkat.

Ketika Dikirim

Ketika memilih driver untuk perangkat yang baru dijumlahkan atau driver baru untuk perangkat yang ada (ubah driver). Misalnya, saat pengguna memilih Tambahkan/Hapus Perangkat Keras dan memilih kelas modem. Atau, pengguna menyisipkan perangkat PnP dan memilih "Pilih Driver Dari Daftar" di Wizard Perangkat Keras Baru yang Ditemukan.

Siapa yang Menangani

Penginstal Bersama Kelas	Dapat menangani
Penginstal Bersama Perangkat	Tidak menangani
Penginstal Kelas	Dapat menangani

Input Alat Penginstal

DeviceInfoSet
Menyediakan handel ke set informasi perangkat yang berisi perangkat tempat pengandar akan dipilih. Ada kelas penyiapan perangkat yang terkait dengan DeviceInfoSet.

DeviceInfoData
Secara opsional memasok pointer ke struktur SP_DEVINFO_DATA yang mengidentifikasi perangkat dalam set informasi perangkat.

Jika DeviceInfoData adalah NULL, permintaan ini adalah memilih driver untuk kelas penyiapan perangkat yang terkait dengan DeviceInfoSet.

Parameter Penginstalan Perangkat
Jika DeviceInfoData bukan NULL, ada parameter penginstalan perangkat (SP_DEVINSTALL_PARAMS) yang terkait dengan DeviceInfoData. Jika DeviceInfoData adalah NULL, ada parameter penginstalan perangkat yang terkait dengan DeviceInfoSet.

Yang menarik adalah DriverPath, yang berisi lokasi INF yang digunakan saat membuat daftar driver.

Parameter Penginstalan Kelas
Struktur SP_SELECTDEVICE_PARAMS dikaitkan dengan DeviceInfoData jika DeviceInfoData bukan NULL. Jika tidak, parameter penginstalan kelas dikaitkan dengan informasi perangkat yang ditetapkan secara keseluruhan.

Output Alat Penginstal

Parameter Penginstalan Perangkat
Alat penginstal dapat mengubah parameter penginstalan perangkat. Namun, itu tidak boleh memodifikasi bidang DriverPath .

Parameter Penginstalan Kelas
Alat penginstal dapat mengubah SP_SELECTDEVICE_PARAMS. Misalnya, alat penginstal mungkin menentukan judul dan/atau instruksi untuk digunakan Windows dalam kotak dialog yang meminta pengguna untuk memilih driver.

Jika alat penginstal menetapkan parameter perangkat pilih baru, versus memodifikasi parameter yang ditetapkan oleh alat penginstal sebelumnya, alat penginstal harus nol bidang yang tidak diaturnya.

Nilai Pengembalian Alat Penginstal

Jika penginstal bersama tidak melakukan apa pun untuk kode DIF ini, penginstal akan mengembalikan NO_ERROR dari pass pra-pemrosesannya. Jika penginstal bersama menangani kode DIF ini, penginstal harus melakukannya dalam pass pra-pemrosesannya dan mengembalikan NO_ERROR atau kode kesalahan Win32. Pada saat penginstal bersama dipanggil untuk pasca-pemrosesan, driver telah dipilih.

Jika penginstal kelas berhasil menangani permintaan ini dan SetupDiCallClassInstaller kemudian harus memanggil handler default, penginstal kelas mengembalikan ERROR_DI_DO_DEFAULT.

Jika penginstal kelas berhasil menangani permintaan ini, termasuk langsung memanggil handler default, penginstal kelas harus mengembalikan NO_ERROR dan SetupDiCallClassInstaller kemudian tidak akan memanggil handler default lagi.

Catatan Penginstal kelas dapat langsung memanggil handler default, tetapi penginstal kelas tidak boleh mencoba menggantikan operasi handler default.

Untuk informasi selengkapnya tentang memanggil handler default, lihat Memanggil Penangan Kode DIF Default.

Jika penginstal kelas mengalami kesalahan, penginstal harus mengembalikan kode kesalahan Win32 yang sesuai dan SetupDiCallClassInstaller kemudian tidak akan memanggil handler default.

Penginstal kelas mengembalikan ERROR_DI_BAD_PATH jika anggota DriverPath dari struktur SP_DEVINSTALL_PARAMS yang sesuai tidak sama dengan NULL, tetapi tidak ada driver yang valid di lokasi jalur yang ditentukan. Ini dapat terjadi jika tidak ada driver di lokasi jalur atau jika ada driver, tetapi anggota Bendera dari struktur SP_DRVINSTALL_PARAMS setiap driver diatur dengan bendera DN_BAD_DRIVER. Menanggapi kode galat ini, Windows menampilkan kesalahan kepada pengguna.

Handler Kode DIF Default

SetupDiSelectDevice

Operasi Alat Penginstal

Menanggapi permintaan DIF_SELECTDEVICE, alat penginstal melakukan operasi pemilihan apa pun yang diperlukan untuk perangkat atau kelas perangkatnya, selain apa yang dilakukan handler default. Alat penginstal biasanya menanggapi permintaan DIF ini dengan salah satu cara berikut:

Tidak melakukan apa pun.

Jika alat penginstal tidak memiliki persyaratan pemilihan khusus, penginstal tidak melakukan apa pun sebagai respons terhadap kode DIF ini. Penginstal kelas mengembalikan ERROR_DI_DO_DEFAULT dan penginstal bersama mengembalikan NO_ERROR.
Berikan string pilih yang akan ditampilkan Windows di UI pilihan.

Alat penginstal dapat menyediakan string tertentu di parameter penginstalan kelas (SP_SELECTDEVICE_PARAMS). Misalnya, alat penginstal dapat mengubah Instruksi atau Judul header jendela.

Alat penginstal kelas tidak boleh menyediakan string tertentu jika penginstal bersama sudah disediakan string tertentu. Penginstal bersama mungkin memiliki informasi yang lebih relevan.

Jika alat penginstal memodifikasi SP_SELECTDEVICE_PARAMS, alat penginstal juga harus mengatur bendera DI_USECI_SELECTSTRINGS di SP_DEVINSTALL_PARAMS.

Jika alat penginstal berhasil menyediakan string tertentu, Windows masih harus memanggil handler default. Oleh karena itu, dalam hal ini, penginstal bersama mengembalikan NO_ERROR dan alat penginstal kelas mengembalikan ERROR_DI_DO_DEFAULT.
Ubah parameter penginstalan perangkat.

Alat penginstal dapat mengubah parameter penginstalan perangkat (SP_DEVINSTALL_PARAMS). Misalnya, alat penginstal mungkin mengatur bendera DI_SHOWOEM agar Windows menampilkan tombol Miliki Disk .

Jika penginstal kelas berhasil memodifikasi parameter penginstalan perangkat, penginstal kelas mengembalikan ERROR_DI_DO_DEFAULT.
Ubah daftar driver tempat pengguna dapat memilih.

Tindakan ini kurang umum, tetapi mungkin. Alat penginstal yang memodifikasi daftar driver mungkin, atau mungkin tidak, juga menyediakan string tertentu.

Alat penginstal yang memodifikasi daftar driver biasanya menandai driver yang tidak pantas untuk perangkat. Alat penginstal menandai driver tersebut dengan bendera DNF_BAD_DRIVER. Windows menghilangkan pengandar ini dari daftar yang ditampilkannya kepada pengguna.

Alat penginstal menandai driver yang buruk dengan mengikuti langkah-langkah berikut:
1. Buat daftar driver dengan memanggil SetupDiBuildDriverInfoList dengan DriverType SPDIT_CLASSDRIVER.
2. Dapatkan informasi tentang driver pertama dalam daftar dengan memanggil SetupDiEnumDriverInfo dan SetupDiGetDriverInstallParams. Jika driver tidak sesuai untuk perangkat, atur bendera DNF_BAD_DRIVER di bidang Bendera parameter. Terapkan perubahan ke parameter dengan memanggil SetupDiSetDriverInstallParams.
3. Ulangi langkah sebelumnya hingga Anda memproses semua driver dalam daftar. Pastikan Anda menaikkan parameter MemberIndex ke SetupDiEnumDriverInfo seperti yang dijelaskan di halaman referensi untuk fungsi tersebut.
Alat penginstal mungkin mengatur bendera DNF_BAD_DRIVER untuk satu atau beberapa driver dalam daftar driver, tetapi alat penginstal tidak boleh menghapus bendera tersebut.

Jika satu atau beberapa alat penginstal berhasil mengubah daftar pengandar, Windows masih harus memanggil penangan default. Oleh karena itu, dalam hal ini, penginstal bersama mengembalikan NO_ERROR dan alat penginstal kelas mengembalikan ERROR_DI_DO_DEFAULT.
Tampilkan antarmuka pengguna pemilihan drivernya sendiri dan atur pengandar terpilih.

Hanya alat penginstal kelas yang dapat menampilkan antarmuka pengguna pemilihan drivernya sendiri; penginstal bersama tidak boleh. Misalnya, alat penginstal kelas mungkin menampilkan gambar alih-alih daftar tekstual.

Jika penginstal kelas berhasil mengatur driver yang dipilih, penginstal kelas mengembalikan NO_ERROR dan Windows tidak memanggil handler default dan karenanya tidak menampilkan antarmuka pemilihan default.

Jika bendera DI_ENUMSINGLEINF diatur dalam parameter penginstalan perangkat, DriverPath adalah jalur dari satu file INF alih-alih jalur direktori. Alat penginstal hanya boleh menggunakan INF tunggal tersebut untuk membuat daftar driver.

Untuk informasi selengkapnya tentang kode DIF, lihat Menangani Kode DIF.