Функция ZwOpenDirectoryObject (ntifs.h)

Статья
03/08/2023

Подпрограмма ZwOpenDirectoryObject открывает существующий объект каталога.

Синтаксис

NTSYSAPI NTSTATUS ZwOpenDirectoryObject(
  [out] PHANDLE            DirectoryHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes
);

Параметры

[out] DirectoryHandle

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

[in] DesiredAccess

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

DesiredAccess Флаги	Значение
DIRECTORY_QUERY	Запрос доступа к объекту каталога
DIRECTORY_TRAVERSE	Доступ подстановки имени к объекту каталога
DIRECTORY_CREATE_OBJECT	Доступ к объекту каталога при создании имени
DIRECTORY_CREATE_SUBDIRECTORY	Доступ к объекту каталога при создании подкаталога
DIRECTORY_ALL_ACCESS	Все указанные выше права и STANDARD_RIGHTS_REQUIRED.

Эти запрошенные типы доступа сравниваются со списком управления доступом (DACL) объекта, чтобы определить, какие доступы предоставляются или запрещаются.

[in] ObjectAttributes

Указанные атрибуты для объекта каталога, предоставленного вызывающим объектом. Этот параметр инициализируется путем вызова макроса InitializeObjectAttributes .

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

ZwOpenDirectoryObject возвращает STATUS_SUCCESS или соответствующее состояние ошибки. Ниже перечислены наиболее распространенные коды состояния ошибок.

Код возврата	Описание
STATUS_INSUFFICIENT_RESOURCES	Не удалось выделить временный буфер, необходимый для этой подпрограммы.
STATUS_INVALID_PARAMETER	Указанный параметр ObjectAttributes был указателем NULL , а не допустимым указателем на структуру OBJECT_ATTRIBUTES , или некоторые поля, указанные в структуре OBJECT_ATTRIBUTES, были недопустимыми.
STATUS_OBJECT_NAME_INVALID	Параметр ObjectAttributes содержал поле ObjectName в структуре OBJECT_ATTRIBUTES , которое было недопустимо, так как после символа OBJECT_NAME_PATH_SEPARATOR была найдена пустая строка.
STATUS_OBJECT_NAME_NOT_FOUND	Параметр ObjectAttributes содержал поле ObjectName в структуре OBJECT_ATTRIBUTES , которое не удалось найти.
STATUS_OBJECT_PATH_NOT_FOUND	Параметр ObjectAttributes содержал поле ObjectName в структуре OBJECT_ATTRIBUTES с не удалось найти путь к объекту.
STATUS_OBJECT_PATH_SYNTAX_BAD	Параметр ObjectAttributes не содержал поле RootDirectory , но поле ObjectName в структуре OBJECT_ATTRIBUTES было пустой строкой или не содержало символ OBJECT_NAME_PATH_SEPARATOR. Это указывает на неправильный синтаксис пути к объекту.

Подпрограмма ZwOpenDirectoryObject создает исключение, если параметр DirectoryHandle является недопустимым указателем.

Подпрограмма ZwOpenDirectoryObject вызывается после макроса InitializeObjectAttributes , используемого для инициализации определенных атрибутов структуры OBJECT_ATTRIBUTES для открываемого объекта.

Объект каталога создается с помощью подпрограммы ZwCreateDirectoryObject. Любой дескриптор, полученный путем вызова ZwOpenDirectoryObject, в конечном итоге должен быть освобожден путем вызова ZwClose.

Дополнительные сведения о безопасности и управлении доступом см. в статье Модель безопасности Windows для разработчиков драйверов и в документации по этим темам в windows SDK.

Примечание Если вызов функции ZwCreateDirectoryObject выполняется в пользовательском режиме, следует использовать имя NtCreateDirectoryObject вместо ZwCreateDirectoryObject.

Для вызовов из драйверов режима ядра версии NtXxx и ZwXxx подпрограммы собственных системных служб Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями процедуры NtXxx и ZwXxx см. в разделе Использование версий Nt и Zw для процедур собственных системных служб.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntdef.h, Ntifs.h, Fltkernel.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)