CM_Query_And_Remove_SubTreeW函式 (cfgmgr32.h)
CM_Query_And_Remove_SubTree函式會檢查是否可以移除裝置實例及其子系，如果是的話，它會移除它們。
語法
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
);
參數
[in] dnAncestor
呼叫端提供的裝置實例句柄，指向要移除之子樹根目錄的裝置。 此裝置實例句柄會系結至本機計算機。
[out, optional] pVetoType
(選擇性) 如果呼叫端未傳遞 NULL ，且移除要求已 (，則函式會在傳回時傳回CR_REMOVE_VETOED) ，這會指向指出 veto 原因的 PNP_VETO_TYPE型別值。
[out, optional] pszVetoName
(選擇性) 如果呼叫端未傳遞 NULL ，且移除要求 (即會傳回CR_REMOVE_VETOED) ，則傳回時，這會指向與 veto 類型相關聯的文字字串。 此字串提供的資訊類型取決於 pVetoType 所收到的值。 如需這些字串的相關信息，請參閱 PNP_VETO_TYPE。
[in] ulNameLength
呼叫端提供的值，代表 pszVetoName 所提供字串緩衝區) 長度 (字元數。 這應該設定為 MAX_PATH。
[in] ulFlags
A bitwise OR of the caller-supplied flag constants that are described in the Remarks section.
傳回值
如果作業成功，函式會傳回CR_SUCCESS。 否則，它會傳回 Cfgmgr32.h 中定義的另一個CR_前置錯誤碼。
備註
CM_Query_And_Remove_SubTree函式的目的是允許應用程式準備裝置，以便從本機計算機安全移除。 只有在驅動程式尚未設定 DEVICE_CAPABILITIES 的 SurpriseRemovalOK 成員時，才使用此函式來移除裝置。 如果驅動程式已設定 SurpriseRemovalOK，應用程式應該呼叫 CM_Request_Device_Eject ，而不是 CM_Query_And_Remove_SubTree。
CM_Query_And_Remove_SubTree 支援使用下列兩個旗標之一來設定 flags 參數 ulFlags ;只有在 Windows 或安裝程式已移除裝置時，才會套用這些旗標：
| 旗標 | 描述 |
|---|---|
| CM_REMOVE_UI_OK | 函式可讓使用者顯示對話框，以指出veto的原因。 這是預設旗標設定。 |
| CM_REMOVE_UI_NOT_OK | 函式會隱藏使用者對話框的顯示，指出veto的原因。 |
從 Windows XP 開始， CM_Query_And_Remove_SubTree 也支援設定下列額外旗標;只有在函式成功移除裝置實例時，才會套用此旗標：
| 旗標 | 描述 |
|---|---|
| CM_REMOVE_NO_RESTART | 如果設定此旗標，函式會設定裝置狀態，讓裝置在重設裝置狀態之前無法重新啟動。 |
裝置狀態會由下列其中一項重設：
- 呼叫裝置 CM_Setup_DevNode 並指定CM_SETUP_DEVNODE_RESET。 以這種方式重設裝置狀態之後，您可以呼叫裝置實例 的CM_Reenumerate_DevNode 來重新啟動裝置。 重設裝置狀態之後，列舉裝置的任何其他作業也會重新啟動裝置，例如，如果使用 裝置管理員 來繼續裝置。
- 裝置已卸離並重新附加，或計算機重新啟動。 在此情況下，將會重設裝置狀態，並重新啟動裝置。
- 如果未設定此旗標，則不需要重設裝置狀態。 您可以藉由為裝置呼叫CM_Setup_DevNode，以及指定 CM_SETUP_DEVNODE_READY 來重新啟動已移除的裝置。 繼續裝置的任何其他作業也會重新啟動裝置。 繼續裝置的作業範例是針對裝置呼叫 CM_Reenumerate_DevNode 、中斷連結和重新附加裝置，或重新啟動計算機。 |
不需要低階作業的 Windows 應用程式 CM_Query_And_Remove_SubTree 應該使用 DIF_PROPERTYCHANGE 要求來停用裝置，而不是使用 CM_Query_And_Remove_SubTree 來移除裝置。 DIF_PROPERTYCHANGE要求可用來啟用、停用、重新啟動、停止或變更裝置的屬性。
此函式的呼叫端必須具有 SeLoadDriverPrivilege。 (許可權說明於 Microsoft Windows SDK documentation.)
如需使用系結至本機計算機的裝置實例句柄的相關信息，請參閱 CM_Get_Child。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | 可在 Microsoft Windows 2000 和更新版本的 Windows 中使用。 |
| 目標平台 | Universal |
| 標頭 | cfgmgr32.h (包含 Cfgmgr32.h) |
| 程式庫 | Cfgmgr32.lib |