InitializeObjectAttributes macro (ntdef.h)

Article
04/02/2021

The InitializeObjectAttributes macro initializes the opaque OBJECT_ATTRIBUTES structure, which specifies the properties of an object handle to routines that open handles.

Syntax

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

Parameters

p

A pointer to the OBJECT_ATTRIBUTES structure to initialize.

n

A pointer to a Unicode string that contains the name of the object for which a handle is to be opened. This must either be a fully qualified object name, or a relative path name to the object directory specified by the RootDirectory parameter.

a

Specifies one or more of the following flags:

Flag	Description
OBJ_INHERIT	This handle can be inherited by child processes of the current process.
OBJ_PERMANENT	This flag only applies to objects that are named within the object manager. By default, such objects are deleted when all open handles to them are closed. If this flag is specified, the object is not deleted when all open handles are closed. Drivers can use ZwMakeTemporaryObject to delete permanent objects.
OBJ_EXCLUSIVE	Only a single handle can be open for this object.
OBJ_CASE_INSENSITIVE	If this flag is specified, a case-insensitive comparison is used when matching the ObjectName parameter against the names of existing objects. Otherwise, object names are compared using the default system settings.
OBJ_OPENIF	If this flag is specified to a routine that creates objects, and that object already exists then the routine should open that object. Otherwise, the routine creating the object returns an NTSTATUS code of STATUS_OBJECT_NAME_COLLISION.
OBJ_KERNEL_HANDLE	Specifies that the handle can only be accessed in kernel mode.
OBJ_FORCE_ACCESS_CHECK	The routine opening the handle should enforce all access checks for the object, even if the handle is being opened in kernel mode.

r

A handle to the root object directory for the path name specified in the ObjectName parameter. If ObjectName is a fully qualified object name, RootDirectory is NULL. Use ZwCreateDirectoryObject ZwCreateDirectoryObject to obtain a handle to an object directory.

s

Specifies a security descriptor to apply to an object when it is created. This parameter is optional. Drivers can specify NULL to accept the default security for the object. For more information, see the following Remarks section.

Return value

None

Remarks

InitializeObjectAttributes initializes an OBJECT_ATTRIBUTES structure that specifies the properties of an object handle to be opened. The caller can then pass a pointer to this structure to a routine that actually opens the handle.

Driver routines that run in a process context other than that of the system process must set the OBJ_KERNEL_HANDLE flag for the Attributes parameter. This flag restricts the use of a handle opened for that object to processes running only in kernel mode. Otherwise, the handle can be accessed by the process in whose context the driver is running.

Note that InitializeObjectAttributes always sets the SecurityQualityOfService member of OBJECT_ATTRIBUTES to NULL. Drivers that require a non-NULL value can set SecurityQualityOfService directly.

Requirements

Requirement	Value
Target Platform	Desktop
Header	ntdef.h (include Wdm.h, Ntddk.h, Ntdef.h)