CM_Query_And_Remove_SubTree_ExA函式 (cfgmgr32.h)

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

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

語法

CMAPI CONFIGRET CM_Query_And_Remove_SubTree_ExA(
  [in]            DEVINST        dnAncestor,
  [out, optional] PPNP_VETO_TYPE pVetoType,
  [out, optional] LPSTR          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

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

傳回值

如果作業成功，函式會傳回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 上執行時存取遠端電腦。

規格需求

另請參閱

CM_Get_Child_Ex
CM_Query_And_Remove_SubTree
CM_Reenumerate_DevNode
CM_Request_Device_Eject_Ex
CM_Setup_DevNode
DIF_PROPERTYCHANGE