CM_Query_And_Remove_SubTree_ExW函式 (cfgmgr32.h)

發行項
02/23/2024

[從 Windows 8 和 Windows Server 2012 開始，此函式已被取代。請改用 CM_Query_And_Remove_SubTree 。]

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

語法

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

參數

[in] dnAncestor

呼叫端提供的裝置實例句柄，指向要移除之子樹根目錄的裝置。此裝置實例句柄會系結至 hMachine 所提供的電腦句柄。

[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

(Optional.) Caller 提供的值，代表 pszVetoName 所提供字串緩衝區) 長度 (字元數。這應該設定為 MAX_PATH。

[in] ulFlags

A bitwise OR of the caller-supplied flag constants that are described in the Remarks section.

[in, optional] hMachine

呼叫端提供的機器句柄，呼叫端提供的裝置實例句柄會系結至其中。

注意從 Windows 8 和 Windows Server 2012 開始，不支援使用此函式來存取遠端電腦，因為已移除此功能。

傳回值

如果作業成功，函式會傳回CR_SUCCESS。否則，它會傳回 Cfgmgr32.h 中定義的其中一個CR_前置錯誤碼。

備註

CM_Query_And_Remove_SubTree_Ex函式的目的是允許應用程式準備裝置，以便從遠端電腦安全移除。只有當驅動程式尚未設定 DEVICE_CAPABILITIES的 SurpriseRemovalOK 成員時，才能使用此函式來移除裝置。如果驅動程式已設定 SurpriseRemovalOK，應用程式應該呼叫 CM_Request_Device_Eject_Ex ，而不是 CM_Query_And_Remove_SubTree_Ex。

CM_Query_And_Remove_SubTree_Ex 支援使用下列兩個旗標之一來設定 flags 參數 ulFlags ;只有在 Windows 或安裝程式已取消移除裝置時，才會套用這些旗標：

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

不需要低階CM_Query_And_Remove_SubTree_Ex作業的裝置安裝應用程式，應該使用DIF_PROPERTYCHANGE要求來停用裝置，而不是使用CM_Query_And_Remove_SubTree_Ex移除裝置。 DIF_PROPERTYCHANGE要求可用來啟用、停用、重新啟動、停止或變更裝置的屬性。

此函式的呼叫端必須具有 SeLoadDriverPrivilege。 Microsoft Windows SDK 檔.) 說明 (許可權

如需使用系結至本機或遠端電腦之裝置實例句柄的相關信息，請參閱 CM_Get_Child_Ex。

存取遠端電腦的功能已在 Windows 8 和 Windows Server 2012 和更新版本的作業系統中移除，因此您無法在這些版本的 Windows 上執行時存取遠端電腦。

規格需求

需求	值
最低支援的用戶端	可在 Microsoft Windows 2000 和更新版本的 Windows 中使用。
目標平台	桌面
標頭	cfgmgr32.h (包含 Cfgmgr32.h)
程式庫	Cfgmgr32.lib