Fungsi DiUninstallDevice (newdev.h)

Artikel
03/08/2023

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
ERROR_ACCESS_DENIED	Pemanggil tidak memiliki hak istimewa Administrator. Secara default, Windows mengharuskan penelepon memiliki hak istimewa Administrator untuk menghapus instalan perangkat.
ERROR_INVALID_FLAGS	Nilai yang ditentukan untuk parameter Bendera tidak sama dengan nol.

Catatan Nilai yang dikembalikan tidak menunjukkan bahwa penghapusan semua devnode anak telah berhasil atau gagal. Dimulai dengan Windows Vista, informasi tentang status penghapusan devnode anak tersedia dalam file Setupapi.dev.log . Untuk informasi selengkapnya tentang file ini, lihat Menyiapkan Log Teks API.

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.

Jika permintaan penghapusan instalasi perangkat memerlukan mulai ulang komputer, DiUninstallDevice meminta pengguna untuk memulai ulang sistem jika parameter NeedReboot diatur ke NULL. Jika ada jendela antarmuka pengguna yang digunakan aplikasi, parameter hwndParent harus diatur ke nilai handel jendela tersebut.

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