共用方式為


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_CAPABILITIESSurpriseRemovalOK 成員時,才使用此函式來移除裝置。 如果驅動程式已設定 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

另請參閱

CM_Get_Child

CM_Query_And_Remove_SubTree_Ex

CM_Reenumerate_DevNode

CM_Request_Device_Eject

CM_Setup_DevNode

DIF_PROPERTYCHANGE