Функция ObCloseHandle (wdm.h)

Статья
03/08/2023

Подпрограмма ObCloseHandle закрывает дескриптор объекта.

Синтаксис

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

Параметры

[in] Handle

Дескриптор для предоставленного системой объекта любого типа.

[in] PreviousMode

Указывает предыдущий режим процессора потока, открывшего дескриптор. Чтобы закрыть дескриптор ядра, задайте для этого параметра значение KernelMode. Чтобы закрыть дескриптор пользователя, задайте для этого параметра значение UserMode. Дополнительные сведения об этих двух типах дескрипторов см. в разделе Примечания.

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

ObCloseHandle возвращает STATUS_SUCCESS, если вызов выполнен успешно. Возможные возвращаемые значения ошибок включают следующие коды NTSTATUS.

Код возврата	Описание
STATUS_INVALID_HANDLE	Дескриптор не является допустимым дескриптором.
STATUS_HANDLE_NOT_CLOSABLE	Вызывающий поток не имеет разрешения на закрытие дескриптора.

Драйвер режима ядра вызывает ObCloseHandle , чтобы закрыть дескриптор любого типа объекта, созданного ядром Windows. Драйвер должен закрыть каждый открывающийся дескриптор, как только дескриптор больше не требуется.

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

Параметр PreviousMode указывает, является ли закрываемый дескриптор дескриптором ядра или пользовательским дескриптором. Чтобы закрыть дескриптор ядра, задайте для параметра PreviousMode значение KernelMode. Чтобы закрыть дескриптор пользователя, задайте для параметра PreviousMode значение UserMode.

Дескриптор ядра — это дескриптор, который открывается системным потоком или драйвером режима ядра, который назначает дескриптору атрибут OBJ_KERNEL_HANDLE. (Например, см. описание OBJ_KERNEL_HANDLE в ZwCreateFile.) Если драйвер в режиме ядра открывает дескриптор для частного использования и этот драйвер выполняется в контексте потока пользовательского режима, драйвер должен открыть дескриптор с атрибутом OBJ_KERNEL_HANDLE. Этот атрибут гарантирует, что дескриптор недоступен для приложений в пользовательском режиме.

Пользовательский дескриптор — это дескриптор, который открывается приложением в пользовательском режиме или драйвером режима ядра, который выполняется в контексте потока пользовательского режима, но не открывает дескриптор с атрибутом OBJ_KERNEL_HANDLE. Если драйвер создает пользовательский дескриптор, используемый приложением в пользовательском режиме, но возникает ошибка, требующая закрытия дескриптора от имени приложения, драйвер может вызвать ObCloseHandle , чтобы закрыть дескриптор.

Подпрограмма ZwClose похожа на ObCloseHandle, но может закрывать только дескриптор ядра. Вызов ZwClose(hObject), который закрывает маркер ядра hObject, имеет тот же эффект, что и вызов ObCloseHandle(hObject, KernelMode). Дополнительные сведения о закрытии дескриптора ядра см. в разделе ZwClose.

Чтобы определить, является ли дескриптор дескриптором ядра или дескриптором пользователя, драйвер, получающий дескриптор, может вызвать подпрограмму ExGetPreviousMode . Кроме того, драйвер может считывать поле RequestorMode из структуры IRP , описывающей запрос ввода-вывода. Диспетчер ввода-вывода задает в поле RequestorMode предыдущий режим процессора потока, запрашивающего операцию ввода-вывода.

Вызывающие объект ObCloseHandle не должны предполагать, что эта подпрограмма автоматически ожидает завершения всех ожидающих операций ввода-вывода перед возвратом.

Дополнительные сведения см. в разделе Дескрипторы объектов.

ObCloseHandle не объявляется в файле заголовка до Windows 7. Чтобы использовать эту подпрограмму в драйвере, включите в код драйвера следующее объявление функции:

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

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h
Библиотека	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL

См. также раздел