IoGetDeviceObjectPointer

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

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

Parameters

ObjectName: Points to a buffer containing a Unicode string that is the name of the device object.
DesiredAccess: Specifies one or more (ORed) system-defined constants, usually FILE_READ_DATA, (infrequently) FILE_WRITE_DATA, and/or FILE_ALL_ACCESS, requesting access rights to the object.
FileObject: Points to the file object that represents the corresponding device object to user-mode code if the call is successful.
DeviceObject: Points 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

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 object(s). 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, which is useful only to highest-level drivers. A lower-level driver should call ObDereferenceObject with the returned file object pointer if such a driver is unloaded to decrement the reference count for the file object. Otherwise, the next-lower driver cannot be unloaded.

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.