CM_Query_And_Remove_SubTree_ExA-Funktion (cfgmgr32.h)

[Ab Windows 8 und Windows Server 2012 ist diese Funktion veraltet. Verwenden Sie stattdessen CM_Query_And_Remove_SubTree .]

Die CM_Query_And_Remove_SubTree_Ex-Funktion überprüft, ob ein Gerät instance und seine untergeordneten Elemente entfernt werden können, und wenn ja, werden sie entfernt.

Syntax

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
);

Parameter

[in] dnAncestor

Das vom Aufrufer bereitgestellte Gerät instance Handle für das Gerät am Stamm der zu entfernenden Unterstruktur. Dieses Gerät instance Handle ist an das von hMachine bereitgestellte Computerhandle gebunden.

[out, optional] pVetoType

(Optional) Wenn der Aufrufer NULL nicht übergibt und die Entfernungsanforderung ein Veto eingibt (d. h. die Funktion gibt CR_REMOVE_VETOED zurück), zeigt dies bei der Rückgabe auf einen PNP_VETO_TYPE typisierten Wert, der den Grund für das Veto angibt.

[out, optional] pszVetoName

(Optional) Wenn der Aufrufer NULL nicht übergibt und die Entfernungsanforderung ein Veto eingibt (d. h. die Funktion gibt CR_REMOVE_VETOED zurück), zeigt dies bei der Rückgabe auf eine Textzeichenfolge, die dem Vetotyp zugeordnet ist. Der Typ der Informationen, die diese Zeichenfolge bereitstellt, hängt vom Wert ab, der von pVetoType empfangen wird. Informationen zu diesen Zeichenfolgen finden Sie unter PNP_VETO_TYPE.

[in] ulNameLength

(Optional.) Vom Aufrufer bereitgestellter Wert, der die Länge (Anzahl der Zeichen) des von pszVetoName bereitgestellten Zeichenfolgenpuffers darstellt. Dies sollte auf MAX_PATH festgelegt werden.

[in] ulFlags

Ein bitweises OR der vom Aufrufer bereitgestellten Flagkonstanten, die im Abschnitt Hinweise beschrieben werden.

[in, optional] hMachine

Vom Aufrufer bereitgestelltes Computerhandle, an das das vom Aufrufer bereitgestellte Gerät instance Handle gebunden ist.

Hinweis Die Verwendung dieser Funktion für den Zugriff auf Remotecomputer wird ab Windows 8 und Windows Server 2012 nicht unterstützt, da diese Funktionalität entfernt wurde.

 

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt die Funktion CR_SUCCESS zurück. Andernfalls wird einer der in Cfgmgr32.h definierten Fehlercodes mit CR_ Präfix zurückgegeben.

Hinweise

Der Zweck der CM_Query_And_Remove_SubTree_Ex-Funktion besteht darin, einer Anwendung zu ermöglichen, ein Gerät für die sichere Entfernung von einem Remotecomputer vorzubereiten. Verwenden Sie diese Funktion, um Geräte nur dann zu entfernen, wenn ein Treiber das SurpriseRemovalOK-Elementvon DEVICE_CAPABILITIES nicht festgelegt hat. Wenn ein Treiber SurpriseRemovalOK festgelegt hat, sollte die Anwendung CM_Request_Device_Eject_Ex anstelle von CM_Query_And_Remove_SubTree_Ex aufrufen.

CM_Query_And_Remove_SubTree_Ex unterstützt das Festlegen des flags-Parameters ulFlags mit einem der folgenden beiden Flags. Diese Flags gelten nur, wenn Windows oder ein Installationsprogramm ein Veto gegen die Entfernung eines Geräts einwendet:

Ab Windows XP unterstützt CM_Query_And_Remove_SubTree_Ex auch das Festlegen des folgenden zusätzlichen Flags: Dieses Flag gilt nur, wenn die Funktion das Gerät erfolgreich entfernt instance:

Geräteinstallationsanwendungen , die nicht den Low-Level-Betrieb von CM_Query_And_Remove_SubTree_Ex erfordern, sollten die DIF_PROPERTYCHANGE-Anforderung verwenden, um ein Gerät zu deaktivieren, anstatt CM_Query_And_Remove_SubTree_Ex zum Entfernen eines Geräts zu verwenden. Die DIF_PROPERTYCHANGE-Anforderung kann verwendet werden, um die Eigenschaften eines Geräts zu aktivieren, zu deaktivieren, neu zu starten, zu beenden oder zu ändern.

Aufrufer dieser Funktion müssen über SeLoadDriverPrivilege verfügen. (Berechtigungen werden in der dokumentation Microsoft Windows SDK beschrieben.)

Informationen zur Verwendung von Geräte- instance Handles, die an einen lokalen oder Remotecomputer gebunden sind, finden Sie unter CM_Get_Child_Ex.

Die Funktionalität für den Zugriff auf Remotecomputer wurde in Windows 8 und Windows Server 2012 und späteren Betriebssystemen entfernt, sodass Sie nicht auf Remotecomputer zugreifen können, wenn Sie unter diesen Versionen von Windows ausgeführt werden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Microsoft Windows 2000 und höheren Versionen von Windows.
Zielplattform	Desktop
Kopfzeile	cfgmgr32.h (include Cfgmgr32.h)
Bibliothek	Cfgmgr32.lib

Weitere Informationen

CM_Get_Child_Ex
CM_Query_And_Remove_SubTree
CM_Reenumerate_DevNode
CM_Request_Device_Eject_Ex
CM_Setup_DevNode
DIF_PROPERTYCHANGE