InitializeObjectAttributes

InitializeObjectAttributes

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

VOID
InitializeObjectAttributes(
    OUT POBJECT_ATTRIBUTES InitializedAttributes,
    IN PUNICODE_STRING ObjectName,
    IN ULONG Attributes,
    IN HANDLE RootDirectory,
    IN PSECURITY_DESCRIPTOR SecurityDescriptor
    );

Parameters

InitializedAttributes

Specifies the OBJECT_ATTRIBUTES structure to initialize.

ObjectName

Specifies the Unicode string 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.

Attributes

Specifies one or more of the following flags:

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.

RootDirectory

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

SecurityDescriptor

Specifies a security descriptor to apply to an object when it is created. Drivers can specify NULL to accept the default security for the object. This parameter is optional.

Return Value

None

Comments

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

Headers: Declared in Ntdef.h. Include Wdm.h or Ntddk.h.