IoGetDeviceObjectPointer function (wdm.h)
The IoGetDeviceObjectPointer routine returns a pointer to the top object in the named device object's stack and a pointer to the corresponding file object, if the requested access to the objects can be granted.
Syntax
NTSTATUS IoGetDeviceObjectPointer(
[in] PUNICODE_STRING ObjectName,
[in] ACCESS_MASK DesiredAccess,
[out] PFILE_OBJECT *FileObject,
[out] PDEVICE_OBJECT *DeviceObject
);
Parameters
[in] ObjectName
Pointer to a buffer that contains a Unicode string that is the name of the device object.
[in] 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.
[out] FileObject
Pointer to the file object that represents the corresponding device object to user-mode code if the call is successful.
[out] DeviceObject
Pointer to the device object that represents the named logical, virtual, or physical device if the call is successful.
Return value
IoGetDeviceObjectPointer returns STATUS_SUCCESS if it is successful. Possible error return values include the following status codes:
STATUS_OBJECT_TYPE_MISMATCH
STATUS_INVALID_PARAMETER
STATUS_PRIVILEGE_NOT_HELD
STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_INVALID
Remarks
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 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.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available starting with Windows 2000. |
| Target Platform | Universal |
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI compliance rules | HwStorPortProhibitedDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm) |