Fungsi UpdateDriverForPlugAndPlayDevicesW (newdev.h)

Artikel
03/08/2023

Mengingat file INF dan ID perangkat keras, fungsi UpdateDriverForPlugAndPlayDevices menginstal driver yang diperbarui untuk perangkat yang cocok dengan ID perangkat keras.

Sintaks

BOOL UpdateDriverForPlugAndPlayDevicesW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR HardwareId,
  [in]            LPCWSTR FullInfPath,
  [in]            DWORD   InstallFlags,
  [out, optional] PBOOL   bRebootRequired
);

Parameter

[in, optional] hwndParent

Handel ke jendela tingkat atas yang akan digunakan untuk UI apa pun yang terkait dengan penginstalan perangkat.

[in] HardwareId

Penunjuk ke string yang dihentikan NULL yang memasok pengidentifikasi perangkat keras agar sesuai dengan perangkat yang ada di komputer. Panjang maksimum pengidentifikasi perangkat keras yang dihentikan NULL adalah MAX_DEVICE_ID_LEN. Untuk informasi selengkapnya tentang pengidentifikasi perangkat keras, lihat String Identifikasi Perangkat.

[in] FullInfPath

Penunjuk ke string yang dihentikan NULL yang menyediakan nama file jalur lengkap file INF. File harus berada di media distribusi atau di direktori yang dibuat vendor, bukan di lokasi sistem seperti %SystemRoot%\inf. UpdateDriverForPlugAndPlayDevices menyalin file driver ke lokasi sistem yang sesuai jika penginstalan berhasil.

[in] InstallFlags

Nilai yang disediakan penelepon yang dibuat dengan menggunakan OR untuk menggabungkan nol atau beberapa bendera bit berikut:

INSTALLFLAG_FORCE

Jika bendera ini diatur dan fungsi menemukan perangkat yang cocok dengan nilai HardwareId , fungsi menginstal driver baru untuk perangkat apakah driver yang lebih baik sudah ada di komputer.

Penting Gunakan bendera ini hanya dengan sangat hati-hati. Mengatur bendera ini dapat menyebabkan driver yang lebih lama diinstal melalui driver yang lebih baru, jika pengguna menjalankan aplikasi vendor setelah driver yang lebih baru tersedia.

INSTALLFLAG_READONLY

Jika bendera ini diatur, fungsi tidak akan menyalin, mengganti nama, atau menghapus file penginstalan apa pun. Penggunaan bendera ini harus terbatas pada lingkungan di mana akses file dibatasi atau tidak mungkin, seperti sistem operasi "tersemat".

INSTALLFLAG_NONINTERACTIVE

Jika bendera ini diatur, fungsi akan mengembalikan FALSE ketika ada upaya untuk menampilkan UI yang terdeteksi. Atur bendera ini hanya jika fungsi akan dipanggil dari komponen (seperti layanan) yang tidak dapat menampilkan UI.

Catatan Jika bendera ini diatur dan tampilan UI dicoba, perangkat dapat dibiarkan dalam status tidak ditentukan.

Parameter InstallFlags biasanya nol.

[out, optional] bRebootRequired

Penunjuk ke variabel berjenis BOOL yang menunjukkan apakah hidupkan ulang diperlukan dan siapa yang harus memintanya. Penunjuk ini bersifat opsional dan dapat berupa NULL.

Jika penunjuk adalah NULL, UpdateDriverForPlugAndPlayDevices meminta restart setelah menginstal driver, jika perlu. Jika pointer disediakan, fungsi mengembalikan nilai BOOLEAN yang TRUE jika sistem harus dimulai ulang. Maka pemanggil bertanggung jawab untuk meminta hidupkan ulang.

Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

Nilai kembali

Fungsi mengembalikan TRUE jika perangkat ditingkatkan ke driver yang ditentukan.

Jika tidak, kesalahan mengembalikan FALSE dan kesalahan yang dicatat dapat diambil dengan panggilan ke GetLastError. Kemungkinan nilai kesalahan yang dikembalikan oleh GetLastError disertakan dalam tabel berikut.

Menampilkan kode	Deskripsi
ERROR_FILE_NOT_FOUND	Jalur yang ditentukan untuk FullInfPath tidak ada.
ERROR_IN_WOW64	Aplikasi panggilan adalah aplikasi 32-bit yang mencoba mengeksekusi di lingkungan 64-bit, yang tidak diizinkan.
ERROR_INVALID_FLAGS	Nilai yang ditentukan untuk InstallFlags tidak valid.
ERROR_NO_SUCH_DEVINST	Nilai yang ditentukan untuk HardwareId tidak cocok dengan perangkat apa pun pada sistem. Artinya, perangkat tidak dicolokkan.
ERROR_NO_MORE_ITEMS	Fungsi menemukan kecocokan untuk nilai HardwareId , tetapi driver yang ditentukan tidak cocok dengan driver saat ini dan pemanggil tidak menentukan bendera INSTALLFLAG_FORCE.

Keterangan

UpdateDriverForPlugAndPlayDevices memindai perangkat pada sistem dan mencoba menginstal driver yang ditentukan oleh FullInfPath untuk perangkat apa pun yang cocok dengan nilai HardwareId yang ditentukan.

Perilaku default adalah hanya menginstal driver yang ditentukan jika mereka lebih cocok daripada driver yang saat ini diinstal dan driver yang ditentukan juga merupakan kecocokan yang lebih baik daripada driver di %SystemRoot%\inf. Untuk informasi selengkapnya, lihat Cara Windows Memilih Driver.

UpdateDriverForPlugAndPlayDevices juga dapat digunakan untuk menentukan apakah perangkat dengan nilai HardwareId yang ditentukan dicolokkan. Untuk informasi selengkapnya, lihat Menulis Aplikasi Penginstalan Perangkat.

UpdateDriverForPlugAndPlayDevices mengirimkan permintaan IRP_MN_QUERY_REMOVE_DEVICE ke perangkat yang ditentukan, semua turunan perangkat, dan semua perangkat lain yang secara rekursif menjadi bagian dari relasi penghapusan untuk perangkat. Jika salah satu perangkat ini gagal menghapus permintaan kueri, UpdateDriverForPlugAndPlayDevices mengatur bendera DI_NEEDREBOOT di anggota Bendera struktur SP_DEVINSTALL_PARAMS untuk perangkat. Untuk informasi tentang relasi penghapusan, lihat permintaan IRP_MN_QUERY_DEVICE_RELATIONS .

Umumnya, aplikasi penginstalan perangkat harus menyediakan NULL untuk bRebootRequired. Jadi, sistem akan memulai hidupkan ulang jika perlu. Aplikasi harus menentukan nilai penunjuk hanya dalam kasus berikut:

Aplikasi harus memanggil UpdateDriverForPlugAndPlayDevices beberapa kali untuk menyelesaikan penginstalan.
Aplikasi harus melakukan operasi lain sebelum hidupkan ulang (jika diperlukan) terjadi.
Aplikasi ini adalah penginstal kelas, yang harus mengatur DI_NEEDREBOOT di SP_DEVINSTALL_PARAMS jika hidupkan ulang diperlukan.

Jika aplikasi harus memanggil UpdateDriverForPlugAndPlayDevices beberapa kali, aplikasi harus menyimpan nilai status hidupkan ulang TRUE yang diterima lalu meminta restart setelah panggilan akhir kembali.

Jika fungsi mengembalikan ERROR_IN_WOW64 dalam aplikasi 32-bit, aplikasi dijalankan pada sistem 64-bit, yang tidak diizinkan. Untuk informasi selengkapnya, lihat Menginstal Perangkat pada Sistem 64-Bit.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Microsoft Windows 2000 dan versi Windows yang lebih baru.
Target Platform	Desktop
Header	newdev.h (termasuk Newdev.h)
Pustaka	Newdev.lib

Bagikan melalui