CM_Query_And_Remove_SubTreeW-Funktion (cfgmgr32.h)

Artikel
08/22/2023

Die CM_Query_And_Remove_SubTree-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_SubTreeW(
  [in]            DEVINST        dnAncestor,
  [out, optional] PPNP_VETO_TYPE pVetoType,
  [out, optional] LPWSTR         pszVetoName,
  [in]            ULONG          ulNameLength,
  [in]            ULONG          ulFlags
);

Parameter

[in] dnAncestor

Das vom Anrufer bereitgestellte Gerät instance das Gerät am Stamm der zu entfernenden Unterstruktur verarbeiten. Dieses Gerät instance Handle ist an den lokalen Computer gebunden.

[out, optional] pVetoType

(Optional) Wenn der Aufrufer NULL nicht übergibt und die Entfernungsanforderung ein Veto ein veto erhält (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 ein Veto einnimmt (d. h. die Funktion gibt CR_REMOVE_VETOED zurück), zeigt dies beim Zurückgeben 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

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 bitweiser OR der vom Aufrufer bereitgestellten Flagkonstanten, die im Abschnitt Hinweise beschrieben werden.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt die Funktion CR_SUCCESS zurück. Andernfalls gibt er einen der anderen CR_-Präfix-Fehlercodes zurück, die in Cfgmgr32.h definiert sind.

Hinweise

Der Zweck der CM_Query_And_Remove_SubTree-Funktion besteht darin, einer Anwendung zu ermöglichen, ein Gerät für die sichere Entfernung vom lokalen Computer vorzubereiten. Verwenden Sie diese Funktion, um Geräte nur zu entfernen, wenn ein Treiber das SurpriseRemovalOK-Element von DEVICE_CAPABILITIES nicht festgelegt hat. Wenn ein Treiber SurpriseRemovalOK festgelegt hat, sollte die Anwendung CM_Request_Device_Eject anstelle von CM_Query_And_Remove_SubTree aufrufen.

CM_Query_And_Remove_SubTree 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 ein veto stellt:

Flag	Beschreibung
CM_REMOVE_UI_OK	Mit der Funktion kann ein Benutzerdialogfeld angezeigt werden, um den Grund für das Veto anzugeben. Dies ist die Standardflaggeeinstellung.
CM_REMOVE_UI_NOT_OK	Die Funktion unterdrückt die Anzeige eines Benutzerdialogfelds, das den Grund für das Veto angibt.

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

Flag	Beschreibung
CM_REMOVE_NO_RESTART	Wenn dieses Flag festgelegt ist, konfiguriert die Funktion das Gerät status so, dass das Gerät erst neu gestartet werden kann, nachdem das Gerät status zurückgesetzt wurde.

Das Gerät status wird wie folgt zurückgesetzt:

Aufrufen CM_Setup_DevNode für das Gerät und Angeben CM_SETUP_DEVNODE_RESET. Nachdem das Gerät status auf diese Weise zurückgesetzt wurde, kann das Gerät neu gestartet werden, indem CM_Reenumerate_DevNode für das Gerät instance aufgerufen wird. Nach dem Zurücksetzen des Geräte-status startet jeder andere Vorgang, der das Gerät aufzählt, auch das Gerät neu, z. B. wenn die Geräte-Manager verwendet wird, um Geräte erneut aufzulisten.
Das Gerät wird getrennt und wieder angefügt, oder der Computer wird neu gestartet. In diesem Fall wird das Gerät status zurückgesetzt, und das Gerät wird neu gestartet.
Wenn dieses Flag nicht festgelegt ist, muss das Gerät status nicht zurückgesetzt werden. Sie können das entfernte Gerät neu starten, indem Sie CM_Setup_DevNode für das Gerät aufrufen und CM_SETUP_DEVNODE_READY angeben. Jeder andere Vorgang, der das Gerät erneut aufzählt, startet das Gerät ebenfalls neu. Ein Beispiel für einen Vorgang, der ein Gerät erneut aufzählt, ist das Aufrufen CM_Reenumerate_DevNode für das Gerät, das Trennen und Erneutes Anfahren des Geräts oder das Neustarten des Computers. |

Windows-Anwendungen, die nicht den Low-Level-Vorgang CM_Query_And_Remove_SubTree erfordern, sollten die DIF_PROPERTYCHANGE-Anforderung verwenden, um ein Gerät zu deaktivieren, anstatt CM_Query_And_Remove_SubTree 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 Microsoft Windows SDK-Dokumentation beschrieben.)

Informationen zur Verwendung von Gerätehandles instance, die an den lokalen Computer gebunden sind, finden Sie unter CM_Get_Child.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Microsoft Windows 2000 und höheren Versionen von Windows.
Zielplattform	Universell
Header	cfgmgr32.h (einschließlich Cfgmgr32.h)
Bibliothek	Cfgmgr32.lib