ObCloseHandle-Funktion (wdm.h)

Artikel
02/27/2024

Die ObCloseHandle-Routine schließt ein Objekthandle.

Syntax

NTSTATUS ObCloseHandle(
  [in] HANDLE          Handle,
  [in] KPROCESSOR_MODE PreviousMode
);

Parameter

[in] Handle

Ein Handle für ein vom System bereitgestelltes Objekt eines beliebigen Typs.

[in] PreviousMode

Gibt den vorherigen Prozessormodus des Threads an, der das Handle geöffnet hat. Um ein Kernelhandle zu schließen, legen Sie diesen Parameter auf KernelMode fest. Um ein Benutzerhandle zu schließen, legen Sie diesen Parameter auf UserMode fest. Weitere Informationen zu diesen beiden Handletypen finden Sie unter Hinweise.

Rückgabewert

ObCloseHandle gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Mögliche Fehlerrückgabewerte sind die folgenden NTSTATUS-Codes.

Rückgabecode	Beschreibung
STATUS_INVALID_HANDLE	Handle ist kein gültiges Handle.
STATUS_HANDLE_NOT_CLOSABLE	Der aufrufende Thread verfügt nicht über die Berechtigung, das Handle zu schließen.

Hinweise

Ein Kernelmodustreiber ruft ObCloseHandle auf, um ein Handle für jeden Objekttyp zu schließen, der vom Windows-Kernel erstellt wird. Ein Treiber muss jedes geöffnete Handle schließen, sobald das Handle nicht mehr benötigt wird.

Nachdem ObCloseHandle das Handle eines Objekts geschlossen hat, muss der Aufrufer das Handle als ungültig behandeln und vermeiden, dass das Handle für den Zugriff auf das Objekt verwendet wird. Andere Handles bleiben jedoch möglicherweise für dasselbe Objekt geöffnet. Während eines ObCloseHandle-Aufrufs verringert das System die Handleanzahl für das Objekt und überprüft, ob das Objekt gelöscht werden kann. Das System löscht das Objekt erst, wenn alle Handles des Objekts geschlossen sind und alle verweisgezählten Zeiger auf das Objekt freigegeben wurden.

Der PreviousMode-Parameter gibt an, ob das zu schließende Handle ein Kernelhandle oder ein Benutzerhandle ist. Um ein Kernelhandle zu schließen, legen Sie PreviousMode auf KernelMode fest. Um ein Benutzerhandle zu schließen, legen Sie PreviousMode auf UserMode fest.

Ein Kernelhandle ist ein Handle, das von einem Systemthread oder einem Kernelmodustreiber geöffnet wird, der dem Handle das attribut OBJ_KERNEL_HANDLE zuweist. (Siehe beispielsweise die Beschreibung der OBJ_KERNEL_HANDLE in ZwCreateFile.) Wenn ein Kernelmodustreiber ein Handle für die private Verwendung öffnet und dieser Treiber im Kontext eines Benutzermodusthreads ausgeführt wird, muss der Treiber das Handle mit dem attribut OBJ_KERNEL_HANDLE öffnen. Dieses Attribut stellt sicher, dass für Anwendungen im Benutzermodus nicht auf das Handle zugegriffen werden kann.

Ein Benutzerhandle ist ein Handle, das von einer Benutzermodusanwendung oder einem Kernelmodustreiber geöffnet wird, der im Kontext eines Benutzermodusthreads ausgeführt wird, aber das Handle nicht mit dem attribut OBJ_KERNEL_HANDLE öffnet. Wenn ein Treiber ein Benutzerhandle erstellt, das von einer Benutzermodusanwendung verwendet werden soll, aber ein Fehler auftritt, der erfordert, dass der Treiber das Handle im Namen der Anwendung schließen muss, kann der Treiber ObCloseHandle aufrufen, um das Handle zu schließen.

Die ZwClose-Routine ähnelt ObCloseHandle , kann jedoch nur Kernelhandle schließen. Der Aufruf von ZwClose(hObject), der das Kernelhandle hObject schließt, hat die gleiche Auswirkung wie der Aufruf ObCloseHandle(hObject, KernelMode). Weitere Informationen zum Schließen eines Kernelhandles finden Sie unter ZwClose.

Um zu bestimmen, ob ein Handle ein Kernelhandle oder ein Benutzerhandle ist, kann ein Treiber, der ein Handle empfängt, die ExGetPreviousMode-Routine aufrufen. Oder der Treiber kann das Feld RequestorMode aus der IRP-Struktur lesen, die die E/A-Anforderung beschreibt. Der E/A-Manager legt das Feld RequestorMode auf den vorherigen Prozessormodus des Threads fest, der den E/A-Vorgang angefordert hat.

Aufrufer von ObCloseHandle sollten nicht davon ausgehen, dass diese Routine automatisch darauf wartet, dass alle ausstehenden E/A-Vorgänge abgeschlossen sind, bevor sie zurückgegeben wird.

Weitere Informationen finden Sie unter Objekthandles.

ObCloseHandle wird vor Windows 7 nicht in einer Headerdatei deklariert. Um diese Routine in Ihrem Treiber zu verwenden, fügen Sie die folgende Funktionsdeklaration in Ihren Treibercode ein:

#if (NTDDI_VERSION < NTDDI_WIN7)
NTKERNELAPI
NTSTATUS
  ObCloseHandle(
    __in HANDLE Handle,
    __in KPROCESSOR_MODE PreviousMode
    );
#endif

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	wdm.h
Bibliothek	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL

Weitere Informationen