Export (0) Print
Expand All
Expand Minimize

IoAttachDevice routine

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.

Syntax


NTSTATUS IoAttachDevice(
  _In_   PDEVICE_OBJECT SourceDevice,
  _In_   PUNICODE_STRING TargetDevice,
  _Out_  PDEVICE_OBJECT *AttachedDevice
);

Parameters

SourceDevice [in]

Pointer to the caller-created device object.

TargetDevice [in]

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

AttachedDevice [out]

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

Remarks

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.

Requirements

Version

Available in Windows 2000 and later versions of Windows.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL

DDI compliance rules

IrqlIoPassive1, HwStorPortProhibitedDDIs

See also

DEVICE_OBJECT
IoAttachDeviceToDeviceStack
IoAttachDeviceToDeviceStackSafe
IoGetRelatedDeviceObject
IoCreateDevice
IoDetachDevice

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft