IoAttachDevice

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(
    IN PDEVICE_OBJECT  SourceDevice,
    IN PUNICODE_STRING  TargetDevice,
    OUT PDEVICE_OBJECT  *AttachedDevice
    );

Parameters

SourceDevice

Pointer to the caller-created device object.

TargetDevice

Pointer to a buffer containing the name of the device object to which the specified SourceDevice is to be attached.

AttachedDevice

Pointer to caller-allocated storage for a pointer. On return, contains a pointer to the target device object if the attachment succeeds.

Return Value

IoAttachDevice can return one of the following NTSTATUS values:

STATUS_SUCCESS
STATUS_INVALID_PARAMETER
STATUS_OBJECT_TYPE_MISMATCH
STATUS_OBJECT_NAME_INVALID
STATUS_INSUFFICIENT_RESOURCES

Headers

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

Comments

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.

Warning:  AttachedDevice must point to a global memory location, such as the driver’s device extension.  IoAttachDevice opens the file object for the target device, updates AttachedDevice, performs the attach, and then closes the file object.  Thus, the source device receives the IRP_MJ_CLEANUP and IRP_MJ_CLOSE requests for the file object before IoAttachDevice returns.  The driver must forward these requests to the target device, and AttachedDevice must be a memory location accessible to the driver’s DispatchCleanup and DispatchClose routines.

Callers of IoAttachDevice must be running at IRQL = PASSIVE_LEVEL.

See Also

DEVICE_OBJECT, IoAttachDeviceToDeviceStack, IoGetRelatedDeviceObject, IoCreateDevice, IoDetachDevice