CM_Query_And_Remove_SubTreeA函式 (cfgmgr32.h)

CM_Query_And_Remove_SubTree函式會檢查是否可以移除裝置實例及其子系，如果是的話，它會移除它們。

語法

CMAPI CONFIGRET CM_Query_And_Remove_SubTreeA(
  [in]            DEVINST        dnAncestor,
  [out, optional] PPNP_VETO_TYPE pVetoType,
  [out, optional] LPSTR          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 或安裝程式已移除裝置時，才會套用這些旗標：

從 Windows XP 開始， CM_Query_And_Remove_SubTree 也支援設定下列額外旗標;只有在函式成功移除裝置實例時，才會套用此旗標：

裝置狀態會由下列其中一項重設：

• 呼叫裝置 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。

規格需求

另請參閱

CM_Get_Child
CM_Query_And_Remove_SubTree_Ex
CM_Reenumerate_DevNode
CM_Request_Device_Eject
CM_Setup_DevNode
DIF_PROPERTYCHANGE