InitializeObjectAttributes 【MSDN翻译】

InitializeObjectAttributes

InitializeObjectAttributes 宏初始化一个OBJECT_ATTRIBUTES 结构体, 当一个例程打开对象时由此结构体指定目标对象的属性。

语法

C++ 

 

VOID InitializeObjectAttributes(

  [out]          POBJECT_ATTRIBUTES   InitializedAttributes,

  [in]           PUNICODE_STRING      ObjectName,

  [in]           ULONG                Attributes,

  [in]           HANDLE               RootDirectory,

  [in, optional] PSECURITY_DESCRIPTOR SecurityDescriptor

);

参数

InitializedAttributes [out] 

输出需要初始化的 OBJECT_ATTRIBUTES 结构体。

ObjectName [in] 

Unicode string 指针，指定需要打开对象的名字。此参数可以是一个对象的全路径，也可以是一个RootDirectory参数的相对路径。

Attributes [in] 

可以是一个或者多个一下的标志:

OBJ_INHERIT 

此句柄可以被当前进程的子进程继承。

OBJ_PERMANENT 

此标志仅对在对象管理器中的命名对象有效。

一般说来对象在所有打开它的句柄都被关闭时被删除。但是如果指定这个标志则即使所有打开对象的句柄都被关闭对象也不会被删除。驱动可以使用ZwMakeTemporaryObject 去删除这个“持久的对象”.

OBJ_EXCLUSIVE 

指定独占式打开，此对象仅能被一个句柄打开。

OBJ_CASE_INSENSITIVE 

如果被指定则系统在与已经存在的对象做ObjectName 的比较匹配时不分大小写，否则使用系统默认的设定。

OBJ_OPENIF 

当指定此标志时，如果一个例程在创建对象时目标对象已经存在则打开对象。

如果未指定此标志，则创建例程返回NTSTATUS code：STATUS_OBJECT_NAME_COLLISION.

 

OBJ_KERNEL_HANDLE 

此句柄仅能用于内核模式下。

OBJ_FORCE_ACCESS_CHECK 

强制打开此对象的例程必须执行所有的访问检查，即使此句柄已经在内核模式下打开。

RootDirectory [in] 

与ObjectName参数匹配的根目录对象，如果ObjectName是对象的全路径则设置此参数为NULL，使用ZwCreateDirectoryObject 获取一个目录对象。

SecurityDescriptor [in, optional] 

指定对象创建时应用于此对象的安全描述符。此参数为可选参数。驱动程序可以使用NULL用于创建一个具有默认安全描述符的对象。更多信息见Remarks节。

Return value

None

Remarks

InitializeObjectAttributes 初始化一个 OBJECT_ATTRIBUTES 结构用于指定一个需要打开的对象的属性。用于调用者在实际打开此句柄的例程中传入此结构体的指针。

除了在系统进程上下文运行中的驱动例程外执行此函数时都必须在参数Attributes 中指定OBJ_KERNEL_HANDLE 属性。此参数限定了句柄仅能被在内核模式下运行的进程打开。 

注意 InitializeObjectAttributes 总是设置 OBJECT_ATTRIBUTES 的SecurityQualityOfService 成员为 NULL. 如驱动需要这个成员可以直接设置（无需用函数）。