Fungsi DiInstallDevice (newdev.h)

Artikel
03/08/2023

Fungsi DiInstallDevice menginstal driver tertentu yang telah diinstal sebelumnya di penyimpanan driver pada perangkat tertentu yang ada dalam sistem.

Sintaks

BOOL DiInstallDevice(
  [in, optional]  HWND             hwndParent,
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in, optional]  PSP_DRVINFO_DATA DriverInfoData,
  [in]            DWORD            Flags,
  [out, optional] PBOOL            NeedReboot
);

Parameter

[in, optional] hwndParent

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

[in] DeviceInfoSet

Handel ke kumpulan informasi perangkat yang berisi elemen informasi perangkat yang mewakili perangkat yang ditentukan.

[in] DeviceInfoData

Penunjuk ke struktur SP_DEVINFO_DATA yang mewakili perangkat yang ditentukan dalam kumpulan informasi perangkat yang ditentukan.

[in, optional] DriverInfoData

Penunjuk ke struktur SP_DRVINFO_DATA yang menentukan driver untuk diinstal pada perangkat yang ditentukan. Parameter ini bersifat opsional dan dapat diatur ke NULL. Jika parameter ini NULL, DiInstallDevice mencari driver yang telah diinstal sebelumnya di penyimpanan driver untuk driver yang paling cocok dengan perangkat yang ditentukan, dan, jika ditemukan, instal driver pada perangkat yang ditentukan.

[in] Flags

Nilai jenis DWORD yang menentukan nol atau bendera berikut:

DIIDFLAG_SHOWSEARCHUI

Jika pemanggil tidak menentukan driver (DriverInfoData diatur ke NULL) dan DiInstallDevice tidak menemukan driver yang telah diinstal sebelumnya yang cocok dengan perangkat yang ditentukan. Sebagai gantinya, DiInstallDevice menampilkan wizard Perangkat Keras Baru yang Ditemukan untuk perangkat.

DIIDFLAG_NOFINISHINSTALLUI

DiInstallDevice tidak memulai halaman wizard selesai-instal atau tindakan selesai-instal. Pemanggil DiInstallDevice harus memulai operasi ini. Pemanggil hanya boleh menentukan bendera ini jika pemanggil mengharuskan halaman wizard selesai-instal dipanggil dalam konteks komponen antarmuka pengguna yang disediakan pemanggil.

DIIDFLAG_INSTALLNULLDRIVER

DiInstallDevice mencoba menginstal driver null pada perangkat yang ditentukan. Jika bendera ini diatur, DiInstallDevice tidak menggunakan parameter DriverInfoData . DiInstallDevice menghapus semua pengaturan perangkat dan, jika perangkat tidak dapat berjalan dalam mode mentah, fungsi mengatur status perangkat ke CM_PROB_FAILED_INSTALL. Jika DiInstallDevice tidak dapat menginstal pengandar null, status perangkat yang dihasilkan sama seperti jika perangkat tersambung untuk pertama kalinya ke komputer dan Windows tidak menemukan driver untuk perangkat tersebut.

DIIDFLAG_INSTALLCOPYINFDRIVERS

Setiap file INF tambahan yang ditentukan melalui direktif CopyINF akan diinstal pada perangkat apa pun yang berlaku. Kegagalan dalam menginstal INF tambahan tidak akan menyebabkan penginstalan INF utama gagal.

[out, optional] NeedReboot

Penunjuk ke nilai jenis BOOL yang diatur DiInstallDevice untuk menunjukkan apakah sistem memulai ulang diperlukan untuk menyelesaikan penginstalan. Parameter ini bersifat opsional dan dapat diatur ke NULL. Jika parameter ini disediakan dan hidupkan ulang sistem diperlukan untuk menyelesaikan penginstalan, DiInstallDevice mengatur nilai ke TRUE. Dalam hal ini, pemanggil bertanggung jawab untuk memulai ulang sistem. Jika parameter ini disediakan dan hidupkan ulang sistem tidak diperlukan, DiInstallDevice mengatur parameter ini ke FALSE. Jika parameter ini NULL dan sistem dimulai ulang diperlukan untuk menyelesaikan penginstalan, DiInstallDevice menampilkan kotak dialog hidupkan ulang sistem.

Nilai kembali

DiInstallDevice mengembalikan TRUE jika fungsi berhasil menginstal driver yang ditentukan pada perangkat yang ditentukan. Jika tidak, DiInstallDevice 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 Vista dan Windows Server 2008 mengharuskan proses panggilan memiliki hak istimewa Administrator untuk menginstal driver pada perangkat.
ERROR_INVALID_FLAGS	Nilai yang ditentukan untuk Bendera bukan nol atau bitwise ATAU dari bendera yang valid.
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

Hanya panggil DiInstallDevice jika perlu menginstal driver tertentu pada perangkat tertentu. Jika tidak, gunakan UpdateDriverForPlugAndPlayDevices atau DiInstallDriver untuk menginstal driver untuk perangkat. Untuk informasi selengkapnya tentang fungsi mana yang akan dipanggil untuk menginstal driver pada perangkat, lihat SetupAPI Functions yang Menyederhanakan Penginstalan Driver.

Sebelum memanggil DiInstallDevice, pemanggil harus mendapatkan struktur SP_DEVINFO_DATA untuk menentukan perangkat dan, secara opsional, struktur SP_DRVINFO_DATA untuk menentukan driver untuk perangkat.

Untuk membuat kumpulan informasi perangkat yang berisi perangkat yang ditentukan dan untuk mendapatkan struktur SP_DEVINFO_DATA untuk perangkat, lakukan salah satu hal berikut ini:

Panggil SetupDiGetClassDevs untuk mengambil kumpulan informasi perangkat yang berisi perangkat lalu panggil SetupDiEnumDeviceInfo untuk menghitung perangkat dalam kumpulan informasi perangkat. Pada setiap panggilan, SetupDiEnumDeviceInfo mengembalikan struktur SP_DEVINFO_DATA yang mewakili perangkat enumerasi dalam kumpulan informasi perangkat. Untuk mendapatkan informasi spesifik tentang perangkat enumerasi, panggil SetupDiGetDeviceProperty dan berikan struktur SP_DEVINFO_DATA yang dikembalikan oleh SetupDiEnumDeviceInfo.
- ATAU-
Panggil SetupDiOpenDeviceInfo untuk menambahkan perangkat dengan ID instans perangkat yang diketahui ke kumpulan informasi perangkat. SetupDiOpenDeviceInfo mengembalikan struktur SP_DEVINFO_DATA yang mewakili perangkat dalam kumpulan informasi perangkat.

Untuk mengambil struktur SP_DRVINFO_DATA untuk driver yang dipilih, panggil SetupDiBuildDriverInfoList untuk menyusun daftar driver untuk perangkat lalu panggil SetupDiEnumDriverInfo untuk menghitung elemen daftar driver untuk perangkat. Untuk setiap driver yang dijumlahkan, SetupDiEnumDriverInfo mengambil struktur SP_DRVINFO_DATA yang mengidentifikasi driver. SetupDiGetDriverInfoDetail juga dapat dipanggil untuk mengambil detail tambahan tentang driver yang dijumlahkan.

Secara umum, aplikasi penginstalan harus mengatur NeedReboot ke NULL. Ini memastikan bahwa DiInstallDevice 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 DiInstallDevice beberapa kali untuk menyelesaikan penginstalan. Dalam hal ini, aplikasi harus merekam apakah nilai TRUENeedReboot dikembalikan oleh salah satu panggilan ke DiInstallDevice dan, jika demikian, meminta pengguna untuk memulai ulang sistem setelah panggilan akhir ke DiInstallDevice kembali.
Aplikasi harus melakukan operasi yang diperlukan, selain memanggil DiInstallDevice, sebelum menghidupkan ulang sistem harus terjadi. Jika sistem menghidupkan ulang diperlukan, aplikasi harus menyelesaikan operasi yang diperlukan lalu meminta pengguna untuk menghidupkan ulang sistem.
Aplikasi ini adalah penginstal kelas, dalam hal ini, penginstal kelas harus mengatur bendera DI_NEEDREBOOT di anggota Bendera struktur SP_DEVINSTALL_PARAMS untuk perangkat.

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
DLL	Newdev.dll