IoAttachDevice

NTSTATUS
    IoAttachDevice(
        IN PDEVICE_OBJECT  SourceDevice,
        IN PUNICODE_STRING  TargetDevice,
        OUT PDEVICE_OBJECT  *AttachedDevice
        );

IoAttachDevice 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.

Parameters

SourceDevice

Points to the caller-created device object.

TargetDevice

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

AttachedDevice

Points 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

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 only be layered 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.

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.

Callers of IoAttachDevice must be running at IRQL PASSIVE_LEVEL.

See Also

IoAttachDeviceToDeviceStack, IoCreateDevice, IoDetachDevice