IoGetDeviceObjectPointer

The IoGetDeviceObjectPointer routine returns a pointer to a named device object and corresponding file object, if the requested access to the objects can be granted.

NTSTATUS 
  IoGetDeviceObjectPointer(
    IN PUNICODE_STRING  ObjectName,
    IN ACCESS_MASK  DesiredAccess,
    OUT PFILE_OBJECT  *FileObject,
    OUT PDEVICE_OBJECT  *DeviceObject
    );

Parameters

ObjectName

Pointer to a buffer containing a Unicode string that is the name of the device object.

DesiredAccess

Specifies the ACCESS_MASK value that represents the desired access. Usually DesiredAccess is FILE_READ_DATA. Infrequently, the FILE_WRITE_DATA, or FILE_ALL_ACCESS access rights are specified.

FileObject

Pointer to the file object that represents the corresponding device object to user-mode code if the call is successful.

DeviceObject

Pointer to the device object that represents the named logical, virtual, or physical device if the call is successful.

Return Value

IoGetDeviceObjectPointer can return one of the following NTSTATUS values:

STATUS_SUCCESS
STATUS_OBJECT_TYPE_MISMATCH
STATUS_INVALID_PARAMETER
STATUS_PRIVILEGE_NOT_HELD
STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_INVALID

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

IoGetDeviceObjectPointer establishes a “connection” between the caller and the next-lower-level driver. A successful caller can use the returned device object pointer to initialize its own device objects. It can also be used as as an argument to IoAttachDeviceToDeviceStack, IoCallDriver, and any routine that creates IRPs for lower drivers. The returned pointer is a required argument to IoCallDriver.

This routine also returns a pointer to the corresponding file object. When unloading, a driver can dereference the file object as a means of indirectly dereferencing the device object. To do so, the driver calls ObDereferenceObject from its Unload routine, passing the file object pointer returned by IoGetDeviceObjectPointer. Failure to dereference the device object in a driver's Unload routine prevents the next-lower driver from being unloaded. However, drivers that close the file object before the unload process must take out an extra reference on the device object before dereferencing the file object. Otherwise, dereferencing the file object can lead to a premature deletion of the device object.

To get a pointer to the highest-level driver in the file system driver stack, a driver must ensure that the file system is mounted; if it is not, this routine traverses the storage device stack. To ensure that the file system is mounted on the storage device, the driver must specify an appropriate access mask, such as FILE_READ_DATA or FILE_WRITE_ATTRIBUTES, in the DesiredAccess parameter. Specifying FILE_READ_ATTRIBUTES does not cause the file system to be mounted.

After any higher-level driver has chained itself over another driver by successfully calling this routine, the higher-level driver must set the StackSize field in its device object to that of the next-lower-level driver’s device object plus one.

Callers of IoGetDeviceObjectPointer must be running at IRQL = PASSIVE_LEVEL.

See Also

ACCESS_MASK, DEVICE_OBJECT, IoAllocateIrp, IoAttachDevice, IoAttachDeviceToDeviceStack, ObDereferenceObject, ObReferenceObjectByPointer