Fungsi DiUninstallDevice (newdev.h)
Fungsi DiUninstallDevice mencopot pemasangan perangkat dan menghapus simpul perangkatnya (devnode) dari sistem. Ini berbeda dari menggunakan SetupDiCallClassInstaller dengan kode DIF_REMOVE karena mencoba menghapus instalan simpul perangkat selain devnode anak yang ada pada saat panggilan.
Sebelum Windows 8 perangkat turunan apa pun yang tidak ada pada saat panggilan tidak akan dihapus instalasinya. Namun, dimulai dengan Windows 8, perangkat turunan apa pun yang tidak ada pada saat panggilan akan dihapus instalasinya.
Sintaks
BOOL DiUninstallDevice(
[in] HWND hwndParent,
[in] HDEVINFO DeviceInfoSet,
[in] PSP_DEVINFO_DATA DeviceInfoData,
[in] DWORD Flags,
[out, optional] PBOOL NeedReboot
);
Parameter
[in] hwndParent
Handel ke jendela tingkat atas yang digunakan untuk menampilkan komponen antarmuka pengguna apa pun yang terkait dengan permintaan penghapusan instalasi untuk perangkat. Parameter ini bersifat opsional dan dapat diatur ke NULL.
[in] DeviceInfoSet
Handel ke kumpulan informasi perangkat yang berisi elemen informasi perangkat. Elemen ini mewakili perangkat yang akan dihapus instalasinya melalui panggilan ini.
[in] DeviceInfoData
Penunjuk ke struktur SP_DEVINFO_DATA yang mewakili perangkat yang ditentukan dalam informasi perangkat yang ditentukan yang permintaan penghapusan instalasinya dilakukan.
[in] Flags
Nilai jenis DWORD yang menentukan bendera penghapusan instalasi perangkat. Dimulai dengan Windows 7, parameter ini harus diatur ke nol.
[out, optional] NeedReboot
Penunjuk ke nilai jenis BOOL yang diatur DiUninstallDevice untuk menunjukkan apakah hidupkan ulang sistem diperlukan untuk menyelesaikan permintaan penghapusan instalasi perangkat. Parameter ini bersifat opsional dan dapat diatur ke NULL.
Jika parameter diberikan dan menghidupkan ulang sistem diperlukan, DiUninstallDevice mengatur nilai ke TRUE. Dalam hal ini, aplikasi harus meminta pengguna untuk memulai ulang sistem. Jika parameter ini disediakan dan hidupkan ulang sistem tidak diperlukan, DiUninstallDevice mengatur nilai ke FALSE.
Jika parameter ini NULL dan hidupkan ulang sistem diperlukan untuk menyelesaikan penghapusan instalasi perangkat, DiUninstallDevice menampilkan kotak dialog hidupkan ulang sistem.
Untuk informasi selengkapnya tentang parameter ini, lihat bagian Keterangan .
Nilai kembali
DiUninstallDevice mengembalikan TRUE jika fungsi berhasil menghapus instalasi simpul perangkat tingkat atas yang mewakili perangkat. Jika tidak, DiUninstallDevice mengembalikan FALSE, dan kesalahan yang dicatat dapat diambil dengan melakukan panggilan ke GetLastError. Daftar berikut menunjukkan beberapa nilai kesalahan yang lebih umum yang mungkin dikembalikan GetLastError untuk API ini:
Menampilkan kode | Deskripsi |
---|---|
|
Pemanggil tidak memiliki hak istimewa Administrator. Secara default, Windows mengharuskan penelepon memiliki hak istimewa Administrator untuk menghapus instalan perangkat. |
|
Nilai yang ditentukan untuk parameter Bendera tidak sama dengan nol. |
Keterangan
DiUninstallDevice melakukan fungsi yang sama dengan SetupDiCallClassInstaller saat digunakan dengan kode DIF_REMOVE . Perbedaan utamanya adalah bahwa devnode anak untuk perangkat tingkat atas juga dihapus. DiUninstallDevice hanya mengembalikan kegagalan jika simpul perangkat tingkat atas gagal dihapus instalasinya, yang konsisten dengan perilaku SetupDiCallClassInstaller saat digunakan dengan kode DIF_REMOVE . Informasi terperinci tentang apakah penghapusan instalasi devnode anak berhasil tersedia dalam file Setupapi.dev.log.
Perangkat yang akan dihapus instalasinya ditentukan dengan menyediakan kumpulan informasi perangkat yang mencakup perangkat yang dirujuk, dan struktur SP_DEVINFO_DATA untuk perangkat tertentu. Ini disediakan dalam parameter DeviceInfoSet dan DeviceInfoData .
Untuk membuat kumpulan informasi perangkat yang berisi perangkat yang ditentukan dan untuk mendapatkan struktur SP_DEVINFO_DATA untuk perangkat, selesaikan salah satu tugas berikut:
-
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.
- Panggil SetupDiEnumDeviceInfo 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.
Namun, jika aplikasi mengelola pemberitahuan mulai ulang sistem yang diperlukan, aplikasi harus mengatur parameter NeedReboot ke nilai non-NULL . DiUninstallDevice mengatur parameter NeedReboot ke TRUE atau FALSE, tergantung pada apakah sistem menghidupkan ulang diperlukan.
Daftar berikut menunjukkan contoh mengapa aplikasi mungkin mengelola mulai ulang sistem:
- Aplikasi harus menghapus instalan beberapa perangkat. Setelah semua perangkat dihapus, aplikasi harus meminta pengguna untuk memulai ulang sistem jika ada panggilan ke DiUninstallDevice yang dikembalikan TRUE di parameter NeedReboot .
- Aplikasi ini mengharuskan beberapa operasi lain terjadi sebelum sistem dapat dimulai ulang. 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 7 dan versi Windows yang lebih baru. |
Target Platform | Desktop |
Header | newdev.h (termasuk Newdev.h) |
Pustaka | Newdev.lib |
DLL | Newdev.dll |