ZwOpenDirectoryObject 函式 (ntifs.h)

發行項
02/26/2024

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或適當的錯誤狀態。最常見的錯誤狀態代碼包括：

傳回碼	Description
STATUS_INSUFFICIENT_RESOURCES	無法配置此例程所需的暫存緩衝區。
STATUS_INVALID_PARAMETER	指定的 ObjectAttributes 參數是 NULL 指標，不是 OBJECT_ATTRIBUTES 結構的有效指標，或OBJECT_ATTRIBUTES結構中指定的部分欄位無效。
STATUS_OBJECT_NAME_INVALID	ObjectAttributes 參數在OBJECT_ATTRIBUTES結構中包含 ObjectName 字段，因為OBJECT_NAME_PATH_SEPARATOR字元之後找到空字串而無效。
STATUS_OBJECT_NAME_NOT_FOUND	ObjectAttributes 參數包含OBJECT_ATTRIBUTES結構中找不到的 ObjectName 字段。
STATUS_OBJECT_PATH_NOT_FOUND	ObjectAttributes 參數包含OBJECT_ATTRIBUTES結構中的 ObjectName 字段，以及找不到的物件路徑。
STATUS_OBJECT_PATH_SYNTAX_BAD	ObjectAttributes 參數不包含 RootDirectory 欄位，但OBJECT_ATTRIBUTES結構中的 ObjectName 字段是空字串，或不包含OBJECT_NAME_PATH_SEPARATOR字元。這表示對象路徑的語法不正確。

如果 DirectoryHandle 參數是不合法的指標，ZwOpenDirectoryObject 例程會擲回例外狀況。

備註

ZwOpenDirectoryObject 會開啟現有的目錄物件，並傳回物件的句柄。

在 InitializeObjectAttributes 宏用來初始化要開啟之物件之OBJECT_ATTRIBUTES結構的特定屬性之後，就會呼叫 ZwOpenDirectoryObject 例程。

使用 ZwCreateDirectoryObject 例程建立目錄物件。呼叫 ZwOpenDirectoryObject 取得的任何句柄最終都必須藉由呼叫 ZwClose 來釋放。

如需安全性和訪問控制的詳細資訊，請參閱適用於驅動程序開發人員的 Windows 安全性模型，以及 Windows SDK 中這些主題的相關文件。

注意如果在使用者模式中呼叫 ZwCreateDirectoryObject 函式，您應該使用名稱 “NtCreateDirectoryObject”，而不是 “ZwCreateDirectoryObject”。

針對來自內核模式驅動程式的呼叫，Windows 原生系統服務例程的 NtXxx 和 ZwXxx 版本會以處理和解譯輸入參數的方式，以不同的方式運作。如需 例程 NtXxx 和 ZwXxx 版本之間關聯性的詳細資訊，請參閱使用原生系統服務例程的 Nt 和 Zw 版本。

規格需求

需求	值
最低支援的用戶端	Windows XP
目標平台	Universal
標頭	ntifs.h (包含 Ntdef.h、Ntifs.h、Fltkernel.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDIS (storport) 、 PowerIrpDDis (wdm)