Export (0) Print
Expand All

InitializeObjectAttributes macro

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 InitializedAttributes,
  [in]            PUNICODE_STRING ObjectName,
  [in]            ULONG Attributes,
  [in]            HANDLE RootDirectory,
  [in, optional]  PSECURITY_DESCRIPTOR SecurityDescriptor
);

Parameters

InitializedAttributes [out]

Specifies the OBJECT_ATTRIBUTES structure to initialize.

ObjectName [in]

A pointer to a Unicode string that contains 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 [in]

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 [in]

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 to obtain a handle to an object directory.

SecurityDescriptor [in, optional]

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

Header

Ntdef.h (include Wdm.h or Ntddk.h)

See also

ExCreateCallback
IoCreateFile
OBJECT_ATTRIBUTES
PsCreateSystemThread
SECURITY_DESCRIPTOR
UNICODE_STRING
ZwCreateDirectoryObject
ZwCreateFile
ZwCreateKey
ZwMakeTemporaryObject
ZwOpenFile
ZwOpenKey
ZwOpenSection
ZwOpenSymbolicLinkObject

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft