Fungsi DiInstallDriverW (newdev.h)

Artikel
03/08/2023

Fungsi DiInstallDriver telah menginstal driver di penyimpanan driver lalu menginstal driver pada perangkat yang ada dalam sistem yang didukung driver.

Sintaks

BOOL DiInstallDriverW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR InfPath,
  [in]            DWORD   Flags,
  [out, optional] PBOOL   NeedReboot
);

Parameter

[in, optional] hwndParent

Handel ke jendela tingkat atas yang digunakan DiInstallDriver untuk menampilkan komponen antarmuka pengguna apa pun yang terkait dengan penginstalan perangkat. Parameter ini bersifat opsional dan dapat diatur ke NULL.

[in] InfPath

Penunjuk ke string yang dihentikan NULL yang memasok jalur file INF yang sepenuhnya memenuhi syarat untuk paket driver.

[in] Flags

Nilai jenis DWORD yang menentukan nol atau kombinasi satu atau beberapa bendera seperti yang dijelaskan di sini (Bendera biasanya diatur ke nol).

Jika Bendera nol, DiInstallDriver hanya menginstal driver yang ditentukan pada perangkat jika driver lebih cocok untuk perangkat daripada driver yang saat ini diinstal pada perangkat. Untuk informasi tentang cara Windows memilih driver untuk perangkat, lihat Cara Windows Memilih Driver.

Jika Bendera menyertakan DIIRFLAG_FORCE_INF, DiInstallDriver menginstal driver yang ditentukan pada perangkat yang cocok apakah driver lebih cocok untuk perangkat daripada driver yang saat ini diinstal pada perangkat. Jika DIIRFLAG_INSTALL_AS_SET juga ditentukan, DIIRFLAG_FORCE_INF diabaikan.

Hati Memaksa penginstalan driver dapat mengakibatkan penggantian driver yang lebih kompatibel atau lebih baru dengan driver yang kurang kompatibel atau lebih lama.

Jika Bendera menyertakan DIIRFLAG_INSTALL_AS_SET (didukung pada Windows 10 versi 1709 dan yang lebih baru), InfPath harus menentukan direktori alih-alih jalur yang sepenuhnya memenuhi syarat ke file INF dan DiInstallDriver akan menginstal semua file INF di direktori tersebut dengan perilaku khusus. Semua paket driver akan ditahapkan ke Penyimpanan Driver tetapi belum akan tersedia untuk diinstal pada perangkat. Pada pematian sistem berikutnya, paket driver ini akan tersedia untuk diinstal pada perangkat ke depannya dan akan diinstal pada perangkat apa pun yang paling cocok dengan perangkat sehingga perangkat siap pada boot sistem berikutnya.

[out, optional] NeedReboot

Penunjuk ke nilai jenis BOOL yang diatur DiInstallDriver untuk menunjukkan apakah hidupkan ulang sistem diperlukan untuk menyelesaikan penginstalan. Parameter ini bersifat opsional dan dapat berupa NULL. Jika parameter disediakan dan menghidupkan ulang sistem diperlukan untuk menyelesaikan penginstalan, DiInstallDriver mengatur nilai ke TRUE. Dalam hal ini, pemanggil harus meminta pengguna untuk memulai ulang sistem. Jika parameter ini disediakan dan menghidupkan ulang sistem tidak diperlukan untuk menyelesaikan penginstalan, DiInstallDriver mengatur nilai ke FALSE. Jika parameter adalah NULL dan sistem menghidupkan ulang diperlukan untuk menyelesaikan penginstalan, DiInstallDriver menampilkan kotak dialog hidupkan ulang sistem. Untuk informasi selengkapnya tentang parameter ini, lihat bagian Keterangan berikut ini.

Nilai kembali

DiInstallDriver mengembalikan TRUE jika fungsi berhasil menginstal paket driver yang ditentukan sebelumnya di penyimpanan driver. DiInstallDriver juga mengembalikan TRUE jika fungsi berhasil menginstal driver pada satu atau beberapa perangkat dalam sistem. Jika paket driver tidak berhasil diinstal di penyimpanan driver, DiInstallDriver mengembalikan FALSE dan kesalahan yang dicatat dapat diambil dengan melakukan panggilan ke GetLastError. Beberapa nilai kesalahan yang lebih umum yang mungkin dikembalikan GetLastError adalah sebagai berikut:

Menampilkan kode	Deskripsi
ERROR_ACCESS_DENIED	Pemanggil tidak memiliki hak istimewa Administrator. Secara default, Windows mengharuskan penelepon memiliki hak istimewa Administrator untuk menginstal paket driver di penyimpanan driver.
ERROR_FILE_NOT_FOUND	Jalur file INF yang ditentukan tidak ada.
ERROR_INVALID_FLAGS	Nilai yang ditentukan untuk Bendera tidak sama dengan nol atau DIIRFLAG_FORCE_INF.
ERROR_IN_WOW64	Aplikasi panggilan adalah aplikasi 32-bit yang mencoba mengeksekusi di lingkungan 64-bit, yang tidak diizinkan. Untuk informasi selengkapnya, lihat Menginstal Perangkat pada Sistem 64-Bit.

Keterangan

DiInstallDriver melakukan operasi berikut:

Instal paket driver sebelumnya di penyimpanan driver. Jika ada contoh paket driver yang sama yang sudah diinstal sebelumnya di penyimpanan driver, DiInstallDriver terlebih dahulu menghapus instans tersebut lalu menambahkan instans baru paket driver ke penyimpanan driver.
Menghitung perangkat yang ada dalam sistem.
Jika Bendera sama dengan nol, instal driver pada perangkat hanya jika driver yang ditentukan lebih cocok untuk perangkat daripada driver yang saat ini diinstal pada perangkat.
Jika Bendera sama dengan DIIRFLAG_FORCE_INF, instal driver pada perangkat terlepas dari apakah paket driver lebih cocok dengan perangkat daripada driver yang saat ini diinstal pada perangkat.

Secara umum, aplikasi penginstalan harus mengatur NeedReboot ke NULL untuk mengarahkan DiInstallDriver untuk meminta pengguna untuk memulai ulang sistem jika hidupkan ulang diperlukan untuk menyelesaikan penginstalan. Aplikasi harus menyediakan pointer NeedReboot hanya dalam kasus berikut:

Aplikasi harus memanggil DiInstallDriver beberapa kali untuk menyelesaikan penginstalan. Dalam hal ini, aplikasi harus merekam apakah nilai TRUENeedReboot dikembalikan oleh salah satu panggilan ke DiInstallDriver dan, jika demikian, meminta pengguna untuk memulai ulang sistem setelah panggilan akhir ke DiInstallDriver kembali.
Aplikasi harus melakukan operasi yang diperlukan, selain memanggil DiInstallDriver, sebelum mulai ulang sistem harus terjadi. Jika sistem menghidupkan ulang diperlukan, aplikasi harus menyelesaikan operasi yang diperlukan lalu meminta pengguna untuk memulai ulang sistem.
Aplikasi ini adalah penginstal kelas, dalam hal ini, alat penginstal kelas harus mengatur bendera DI_NEEDREBOOT di anggota Bendera struktur SP_DEVINSTALL_PARAMS untuk perangkat.

Untuk menginstal pengandar terpilih pada perangkat yang dipilih, panggil DiInstallDevice. Untuk informasi selengkapnya, lihat Menyiapkan Fungsi API yang Menyederhanakan Penginstalan Driver.

Catatan

Header newdev.h mendefinisikan DiInstallDriver 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
Klien minimum yang didukung	Tersedia di Windows Vista dan versi Windows yang lebih baru.
Target Platform	Desktop
Header	newdev.h (termasuk Newdev.h)
Pustaka	Newdev.lib

Lihat juga

DiInstallDevice