ZwOpenDirectoryObject 函式（ntifs.h）

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

傳回碼	描述
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字元。這表示對象路徑的語法不正確。

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

言論

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

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

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

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

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

對於內核模式驅動程式的呼叫，NtXxx 和 ZwXxx 版本的 Windows 原生系統服務例程，在處理和解譯輸入參數的方式上可能會有不同的行為。如需 nt NtXxx 與 ZwXxx 例程之間關聯性的詳細資訊，請參閱使用 Nt 和 Zw 版本的原生系統服務例程。

要求

要求	價值
最低支援的用戶端	Windows XP
目標平臺	普遍
標頭	ntifs.h （包括 Ntdef.h、Ntifs.h、Fltkernel.h）
連結庫	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDIs（storport），PowerIrpDDis（wdm）