fungsi CM_Query_And_Remove_SubTreeW (cfgmgr32.h)

Artikel
03/08/2023

Fungsi CM_Query_And_Remove_SubTree memeriksa apakah instans perangkat dan turunannya dapat dihapus dan, jika demikian, ia menghapusnya.

Sintaks

CMAPI CONFIGRET CM_Query_And_Remove_SubTreeW(
  [in]            DEVINST        dnAncestor,
  [out, optional] PPNP_VETO_TYPE pVetoType,
  [out, optional] LPWSTR         pszVetoName,
  [in]            ULONG          ulNameLength,
  [in]            ULONG          ulFlags
);

Parameter

[in] dnAncestor

Pegangan instans perangkat yang disediakan penelepon ke perangkat di akar subtree yang akan dihapus. Handel instans perangkat ini terikat ke komputer lokal.

[out, optional] pVetoType

[out, optional] pszVetoName

(Opsional) Jika pemanggil tidak melewati NULL dan permintaan penghapusan direnovasi (artinya, fungsi mengembalikan CR_REMOVE_VETOED), pada pengembalian ini menunjuk ke string teks yang terkait dengan jenis veto. Jenis informasi yang disediakan string ini tergantung pada nilai yang diterima oleh pVetoType. Untuk informasi tentang string ini, lihat PNP_VETO_TYPE.

[in] ulNameLength

Nilai yang disediakan penelepon mewakili panjang (jumlah karakter) buffer string yang disediakan oleh pszVetoName. Ini harus diatur ke MAX_PATH.

[in] ulFlags

Bitwise ATAU konstanta bendera yang disediakan pemanggil yang dijelaskan di bagian Keterangan .

Menampilkan nilai

Jika operasi berhasil, fungsi akan mengembalikan CR_SUCCESS. Jika tidak, kode tersebut mengembalikan salah satu kode kesalahan awalan CR_ lainnya yang ditentukan dalam Cfgmgr32.h.

Keterangan

Tujuan dari fungsi CM_Query_And_Remove_SubTree adalah untuk memungkinkan aplikasi menyiapkan perangkat untuk penghapusan yang aman dari komputer lokal. Gunakan fungsi ini untuk menghapus perangkat hanya jika driver belum mengatur anggota SurpriseRemovalOKdari DEVICE_CAPABILITIES. Jika driver telah mengatur SurpriseRemovalOK, aplikasi harus memanggil CM_Request_Device_Eject alih-alih CM_Query_And_Remove_SubTree.

CM_Query_And_Remove_SubTree mendukung pengaturan parameter bendera ulFlags dengan salah satu dari dua bendera berikut; bendera ini hanya berlaku jika Windows atau alat penginstal melakukan veto penghapusan perangkat:

Bendera	Deskripsi
CM_REMOVE_UI_OK	Fungsi ini memungkinkan kotak dialog pengguna ditampilkan untuk menunjukkan alasan veto. Ini adalah pengaturan bendera default.
CM_REMOVE_UI_NOT_OK	Fungsi ini menekan tampilan kotak dialog pengguna yang menunjukkan alasan veto.

Dimulai dengan Windows XP, CM_Query_And_Remove_SubTree juga mendukung pengaturan bendera tambahan berikut; bendera ini hanya berlaku jika fungsi berhasil menghapus instans perangkat:

Bendera	Deskripsi
CM_REMOVE_NO_RESTART	Jika bendera ini diatur, fungsi mengonfigurasi status perangkat sehingga perangkat tidak dapat dimulai ulang sampai setelah status perangkat diatur ulang.

Status perangkat diatur ulang oleh salah satu hal berikut ini:

Memanggil CM_Setup_DevNode untuk perangkat dan menentukan CM_SETUP_DEVNODE_RESET. Setelah status perangkat diatur ulang dengan cara ini, perangkat dapat dimulai ulang dengan memanggil CM_Reenumerate_DevNode untuk instans perangkat. Setelah mengatur ulang status perangkat, operasi lain yang menghitung perangkat juga akan menghidupkan ulang perangkat, misalnya, jika Manajer Perangkat digunakan untuk menghitung ulang perangkat.
Perangkat dilepas dan dipasang kembali, atau komputer dimulai ulang. Dalam hal ini, status perangkat akan diatur ulang dan perangkat akan dimulai ulang.
Jika bendera ini tidak diatur, status perangkat tidak harus diatur ulang. Anda dapat memulai ulang perangkat yang dihapus dengan memanggil CM_Setup_DevNode untuk perangkat dan dengan menentukan CM_SETUP_DEVNODE_READY. Operasi lain yang menghitung ulang perangkat juga akan menghidupkan ulang perangkat. Contoh operasi yang menghitung ulang perangkat memanggil CM_Reenumerate_DevNode untuk perangkat, melepaskan dan melampirkan kembali perangkat, atau menghidupkan ulang komputer. |

Aplikasi Windows yang tidak memerlukan operasi tingkat rendah CM_Query_And_Remove_SubTree harus menggunakan permintaan DIF_PROPERTYCHANGE untuk menonaktifkan perangkat alih-alih menggunakan CM_Query_And_Remove_SubTree untuk menghapus perangkat. Permintaan DIF_PROPERTYCHANGE dapat digunakan untuk mengaktifkan, menonaktifkan, menghidupkan ulang, menghentikan, atau mengubah properti perangkat.

Pemanggil fungsi ini harus memiliki SeLoadDriverPrivilege. (Hak istimewa dijelaskan dalam dokumentasi Microsoft Windows SDK.)

Untuk informasi tentang menggunakan handel instans perangkat yang terikat ke komputer lokal, lihat CM_Get_Child.

Persyaratan

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