CloseHandle-Funktion (handleapi.h)

Artikel
08/24/2023

Schließt ein geöffnetes Objekthandle.

Syntax

BOOL CloseHandle(
  [in] HANDLE hObject
);

Parameter

[in] hObject

Ein gültiges Handle für ein geöffnetes Objekt.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Wenn die Anwendung unter einem Debugger ausgeführt wird, löst die Funktion eine Ausnahme aus, wenn sie entweder einen ungültigen Handlewert oder einen Pseudohandleswert empfängt. Dies kann passieren, wenn Sie ein Handle zweimal schließen oder CloseHandle für ein Handle aufrufen, das von der FindFirstFile-Funktion zurückgegeben wird, anstatt die FindClose-Funktion aufzurufen.

Hinweise

Die CloseHandle-Funktion schließt Handles für die folgenden Objekte:

Zugriffstoken
Kommunikationsgerät
Konsoleneingabe
Konsolenbildschirmpuffer
Ereignis
Datei
Dateizuordnung
E/A-Abschlussport
Auftrag
Mailslot
Benachrichtigung zur Speicherressource
Mutex
Named Pipe
Pipe
Prozess
Semaphore
Thread
Transaktion
Wartebarer Timer

Die Dokumentation für die Funktionen, die diese Objekte erstellen, gibt an, dass CloseHandle verwendet werden soll, wenn Sie mit dem Objekt fertig sind, und was mit ausstehenden Vorgängen für das Objekt geschieht, nachdem das Handle geschlossen wurde. Im Allgemeinen ungültigt CloseHandle das angegebene Objekthandle, verringert die Handleanzahl des Objekts und führt Überprüfungen der Objektaufbewahrung durch. Nachdem das letzte Handle für ein Objekt geschlossen wurde, wird das Objekt aus dem System entfernt. Eine Zusammenfassung der Erstellerfunktionen für diese Objekte finden Sie unter Kernelobjekte.

Im Allgemeinen sollte eine Anwendung CloseHandle einmal für jedes geöffnete Handle aufrufen. Es ist in der Regel nicht erforderlich, CloseHandle aufzurufen, wenn eine Funktion, die ein Handle verwendet, mit ERROR_INVALID_HANDLE fehlschlägt, da dieser Fehler in der Regel darauf hinweist, dass das Handle bereits ungültig ist. Einige Funktionen verwenden jedoch ERROR_INVALID_HANDLE, um anzugeben, dass das Objekt selbst nicht mehr gültig ist. Eine Funktion, die versucht, ein Handle für eine Datei in einem Netzwerk zu verwenden, kann beispielsweise mit ERROR_INVALID_HANDLE fehlschlagen, wenn die Netzwerkverbindung getrennt wird, da das Dateiobjekt nicht mehr verfügbar ist. In diesem Fall sollte die Anwendung das Handle schließen.

Wenn ein Handle ausgeführt wird, sollten alle An eine Transaktion gebundenen Handles geschlossen werden, bevor ein Commit für die Transaktion ausgeführt wird. Wenn ein Transaktionshandle durch Aufrufen von CreateFileTransacted mit dem FILE_FLAG_DELETE_ON_CLOSE-Flag geöffnet wurde, wird die Datei erst gelöscht, wenn die Anwendung das Handle schließt und CommitTransaction aufruft. Weitere Informationen zu transaktionierten Objekten finden Sie unter Arbeiten mit Transaktionen.

Durch das Schließen eines Threadhandles wird der zugeordnete Thread nicht beendet oder das Threadobjekt entfernt. Durch das Schließen eines Prozesshandles wird der zugeordnete Prozess nicht beendet oder das Prozessobjekt entfernt. Um ein Threadobjekt zu entfernen, müssen Sie den Thread beenden und dann alle Handles für den Thread schließen. Weitere Informationen finden Sie unter Beenden eines Threads. Um ein Prozessobjekt zu entfernen, müssen Sie den Prozess beenden und dann alle Handles für den Prozess schließen. Weitere Informationen finden Sie unter Beenden eines Prozesses.

Das Schließen eines Handles für eine Dateizuordnung kann auch dann erfolgreich sein, wenn noch geöffnete Dateiansichten vorhanden sind. Weitere Informationen finden Sie unter Schließen eines Dateizuordnungsobjekts.

Verwenden Sie nicht die CloseHandle-Funktion , um einen Socket zu schließen. Verwenden Sie stattdessen die Closesocket-Funktion , die alle ressourcen freigibt, die dem Socket zugeordnet sind, einschließlich des Handles für das Socketobjekt. Weitere Informationen finden Sie unter Socket-Schließung.

Verwenden Sie die CloseHandle-Funktion nicht, um ein Handle für einen geöffneten Registrierungsschlüssel zu schließen. Verwenden Sie stattdessen die RegCloseKey-Funktion . CloseHandle schließt das Handle für den Registrierungsschlüssel nicht, gibt jedoch keinen Fehler zurück, um auf diesen Fehler hinzuweisen.

Beispiele

dwPriorityClass = 0;
hProcess = OpenProcess( PROCESS_ALL_ACCESS, FALSE, pe32.th32ProcessID );
if( hProcess == NULL )
	printError( TEXT("OpenProcess") );
else
{
	dwPriorityClass = GetPriorityClass( hProcess );
	if( !dwPriorityClass )
	printError( TEXT("GetPriorityClass") );
	CloseHandle( hProcess );
}

Dieses Beispiel im Kontext finden Sie unter Erstellen einer Momentaufnahme und Anzeigen von Prozessen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	handleapi.h (Einschließen von Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll