InitializeObjectAttributes 宏 (ntdef.h)

项目
08/25/2023

InitializeObjectAttributes 宏初始化不透明的OBJECT_ATTRIBUTES结构，该结构指定打开句柄的例程的对象句柄的属性。

语法

VOID InitializeObjectAttributes(
  [out]          POBJECT_ATTRIBUTES   p,
  [in]           PUNICODE_STRING      n,
  [in]           ULONG                a,
  [in]           HANDLE               r,
  [in, optional] PSECURITY_DESCRIPTOR s
);

parameters

p

指向要初始化 OBJECT_ATTRIBUTES 结构的指针。

n

指向 Unicode 字符串的指针，该字符串包含要为其打开句柄的对象的名称。这必须是完全限定的对象名称，或者 RootDirectory 参数指定的对象目录的相对路径名。

a

指定以下一个或多个标志：

标志	描述
OBJ_INHERIT	此句柄可由当前进程的子进程继承。
OBJ_PERMANENT	此标志仅适用于在对象管理器中命名的对象。默认情况下，关闭所有打开的句柄时，会删除此类对象。如果指定了此标志，则不会在关闭所有打开的句柄时删除对象。驱动程序可以使用 ZwMakeTemporaryObject 删除永久对象。
OBJ_EXCLUSIVE	只能为此对象打开一个句柄。
OBJ_CASE_INSENSITIVE	如果指定了此标志，则当将 ObjectName 参数与现有对象的名称匹配时，将使用不区分大小写的比较。否则，将使用默认系统设置比较对象名称。
OBJ_OPENIF	如果将此标志指定给创建对象的例程，并且该对象已存在，则该例程应打开该对象。否则，创建对象的例程将返回 NTSTATUS 代码STATUS_OBJECT_NAME_COLLISION。
OBJ_KERNEL_HANDLE	指定只能在内核模式下访问句柄。
OBJ_FORCE_ACCESS_CHECK	打开句柄的例程应强制对对象执行所有访问检查，即使该句柄是在内核模式下打开的。

r

ObjectName 参数中指定的路径名的根对象目录的句柄。如果 ObjectName 是完全限定的对象名称，则 RootDirectory 为 NULL。使用 ZwCreateDirectoryObject ZwCreateDirectoryObject 获取对象目录的句柄。

s

指定要在创建对象时应用于对象的安全描述符。此参数是可选的。驱动程序可以指定 NULL 以接受对象的默认安全性。有关更多信息，请参见下面的“备注”部分。

返回值

无

备注

InitializeObjectAttributes 初始化 OBJECT_ATTRIBUTES 结构，该结构指定要打开的对象句柄的属性。然后，调用方可以将指向此结构的指针传递给实际打开句柄的例程。

在系统进程以外的进程上下文中运行的驱动程序例程必须为 Attributes 参数设置OBJ_KERNEL_HANDLE标志。此标志将针对该对象打开的句柄的使用限制为仅在内核模式下运行的进程。否则，运行驱动程序的上下文的进程可以访问句柄。

请注意，InitializeObjectAttributes 始终将 OBJECT_ATTRIBUTES 的 SecurityQualityOfService 成员设置为 NULL。需要非 NULL 值的驱动程序可以直接设置 SecurityQualityOfService 。