Функция CloseHandle (handleapi.h)

Статья
08/24/2023

Закрывает открытый дескриптор объекта.

Синтаксис

BOOL CloseHandle(
  [in] HANDLE hObject
);

Параметры

[in] hObject

Допустимый дескриптор открытого объекта.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Если приложение выполняется в отладчике, функция создает исключение, если получает недопустимое значение дескриптора или псевдо-дескриптор. Это может произойти, если закрыть дескриптор дважды или вызвать Метод CloseHandle для дескриптора, возвращаемого функцией FindFirstFile , вместо вызова функции FindClose .

Маркер доступа
Устройство связи
Входные данные консоли
Буфер экрана консоли
Событие
File
Сопоставление файлов
Порт завершения ввода-вывода
Задание
Mailslot
Уведомление о ресурсе памяти
Mutex
Именованный канал
канал
Процесс
Semaphore
Thread
Транзакция
Таймер для ожидания

В документации по функциям, создающим эти объекты, указано, что closeHandle следует использовать по завершении работы с объектом и что происходит с ожидающими операциями с объектом после закрытия дескриптора. Как правило, CloseHandle делает недействительным указанный дескриптор объекта, уменьшает число дескрипторов объекта и выполняет проверки хранения объектов. После закрытия последнего дескриптора объекта объект удаляется из системы. Сводные сведения о функциях создателя для этих объектов см. в разделе Объекты ядра.

Как правило, приложение должно вызывать CloseHandle один раз для каждого открываемого дескриптора. Обычно вызов CloseHandle не требуется, если функция, использующая дескриптор, завершается сбоем с ERROR_INVALID_HANDLE, так как эта ошибка обычно указывает на то, что дескриптор уже признан недействительным. Однако некоторые функции используют ERROR_INVALID_HANDLE, чтобы указать, что сам объект больше недействителен. Например, функция, которая пытается использовать дескриптор файла в сети, может завершиться сбоем с ERROR_INVALID_HANDLE, если сетевое подключение разорвано, так как объект файла больше недоступен. В этом случае приложение должно закрыть дескриптор.

Если дескриптор выполняет транзакцию, все дескрипторы, привязанные к транзакции, должны быть закрыты перед фиксацией транзакции. Если дескриптор транзакций был открыт путем вызова CreateFileTransacted с флагом FILE_FLAG_DELETE_ON_CLOSE, файл не удаляется, пока приложение не закроет дескриптор и не вызовет CommitTransaction. Дополнительные сведения о транзакциях см. в разделе Работа с транзакциями.

Закрытие дескриптора потока не приводит к завершению связанного потока или удалению объекта потока. Закрытие дескриптора процесса не приводит к завершению связанного процесса или удалению объекта процесса. Чтобы удалить объект потока, необходимо завершить поток, а затем закрыть все дескрипторы потока. Дополнительные сведения см. в разделе Завершение потока. Чтобы удалить объект процесса, необходимо завершить процесс, а затем закрыть все дескрипторы для процесса. Дополнительные сведения см. в разделе Завершение процесса.

Закрытие дескриптора для сопоставления файлов может быть успешным даже при наличии открытых представлений файлов. Дополнительные сведения см. в разделе Закрытие объекта сопоставления файлов.

Не используйте функцию CloseHandle для закрытия сокета. Вместо этого используйте функцию closesocket , которая освобождает все ресурсы, связанные с сокетом, включая дескриптор объекта сокета. Дополнительные сведения см. в разделе Закрытие сокета.

Не используйте функцию CloseHandle для закрытия дескриптора открытого раздела реестра. Вместо этого используйте функцию RegCloseKey . CloseHandle не закрывает дескриптор раздела реестра, но не возвращает ошибку, указывая на этот сбой.

Примеры

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

Чтобы увидеть этот пример в контексте, см. статью Создание моментального снимка и просмотр процессов.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Профессиональная [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows 2000 Server [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	handleapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll