The IoAttachDevice routine attaches the caller's device object to a named target device object, so that I/O requests bound for the target device are routed first to the caller.
NTSTATUS IoAttachDevice( PDEVICE_OBJECT SourceDevice, PUNICODE_STRING TargetDevice, PDEVICE_OBJECT *AttachedDevice );
Pointer to the caller-created device object.
Pointer to a buffer containing the name of the device object to which the specified SourceDevice is to be attached.
Pointer to caller-allocated storage for a pointer. On return, contains a pointer to the target device object if the attachment succeeds.
IoAttachDevice can return one of the following NTSTATUS values:
IoAttachDevice establishes layering between drivers so that the same IRPs can be sent to each driver in the chain.
This routine is used by intermediate drivers during initialization. It allows such a driver to attach its own device object to another device in such a way that any requests being made to the original device are given first to the intermediate driver.
The caller can be layered only at the top of an existing chain of layered drivers. IoAttachDevice searches for the highest device object layered over TargetDevice and attaches to that object (that can be the TargetDevice). Therefore, this routine must not be called if a driver that must be higher-level has already layered itself over the target device.
Note that for file system drivers and drivers in the storage stack, IoAttachDevice opens the target device with FILE_READ_ATTRIBUTES and then calls IoGetRelatedDeviceObject. This does not cause a file system to be mounted. Thus, a successful call to IoAttachDevice returns the device object of the storage driver, not that of the file system driver.
This routine sets the AlignmentRequirement in SourceDevice to the value in the next-lower device object and sets the StackSize to the value in the next-lower object plus one.
|Minimum supported client||Available in Windows 2000 and later versions of Windows.|
|Header||wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)|
|DDI compliance rules||IrqlIoPassive1, HwStorPortProhibitedDDIs|