CM_Query_And_Remove_SubTreeA-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_SubTreeA(
  [in]            DEVINST        dnAncestor,
  [out, optional] PPNP_VETO_TYPE pVetoType,
  [out, optional] LPSTR          pszVetoName,
  [in]            ULONG          ulNameLength,
  [in]            ULONG          ulFlags
);

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 den lokalen Computer gebunden.

[out, optional] pVetoType

[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

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.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt die Funktion CR_SUCCESS zurück. Andernfalls wird einer der anderen fehlercodes mit CR_-Präfix zurückgegeben, 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 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 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 einwendet:

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 Standardflagseinstellung.
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 durch eine der folgenden Zurücksetzungen zurückgesetzt:

Aufrufen CM_Setup_DevNode für das Gerät und Angeben von 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äts 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 einen 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 erneute Anfügen des Geräts oder der Neustart des Computers. |

Windows-Anwendungen, die keinen Low-Level-Vorgang erfordern , CM_Query_And_Remove_SubTree 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 dokumentation Microsoft Windows SDK beschrieben.)

Informationen zur Verwendung von Geräte- instance Handles, 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 (include Cfgmgr32.h)
Bibliothek	Cfgmgr32.lib

Weitere Informationen

CM_Get_Child
CM_Query_And_Remove_SubTree_Ex
CM_Reenumerate_DevNode
CM_Request_Device_Eject
CM_Setup_DevNode
DIF_PROPERTYCHANGE

Freigeben über