Функция IoAttachDeviceToDeviceStackSafe (ntddk.h)

Статья
02/29/2024

Подпрограмма IoAttachDeviceToDeviceStackSafe присоединяет объект устройства вызывающего объекта к самому верхнему объекту устройства в стеке драйверов.

Синтаксис

NTSTATUS IoAttachDeviceToDeviceStackSafe(
  [in]  PDEVICE_OBJECT SourceDevice,
  [in]  PDEVICE_OBJECT TargetDevice,
  [out] PDEVICE_OBJECT *AttachedToDeviceObject
);

Параметры

[in] SourceDevice

Указатель на созданный вызывающим объектом устройства.

[in] TargetDevice

Указатель на объект устройства в стеке, к которому должен быть присоединен объект SourceDevice .

[out] AttachedToDeviceObject

На входных данных этот параметр указывает адрес SourceDevice-DeviceExtension-AttachedToDeviceObject>>, который должен содержать указатель NULL. В выходных данных этот параметр получает указатель на объект устройства, к которому был подключен SourceDevice .

Возвращаемое значение

IoAttachDeviceToDeviceStackSafe возвращает STATUS_SUCCESS, если SourceDevice успешно присоединен над TargetDevice; в противном случае возвращается STATUS_NO_SUCH_DEVICE.

Как и IoAttachDeviceToDeviceStack, IoAttachDeviceToDeviceStackSafe устанавливает слои между драйверами, чтобы те же IRP отправлялись каждому драйверу в стеке. Однако в отличие от IoAttachDeviceToDeviceStack, IoAttachDeviceToDeviceStackSafe имеет дополнительный параметр AttachedToDeviceObject, который драйвер фильтра использует для передачи адреса поля AttachedToDeviceObject объекта SourceDevice . IoAttachDeviceToDeviceStackSafe обновляет это поле, удерживая блокировку системной базы данных ввода-вывода. Так как она удерживает эту блокировку, IoAttachDeviceToDeviceStackSafe позволяет избежать состояния гонки, которое могло бы возникнуть, если объект SourceDevice получил IRP до обновления поля AttachedToDeviceObject.

Драйвер фильтра файловой системы вызывает IoAttachDeviceToDeviceStackSafe для подключения собственного объекта устройства фильтра (SourceDevice) над объектом устройства (TargetDevice), принадлежащим файловой системе или другому драйверу фильтра. Последующие запросы ввода-вывода, отправляемые в AttachedToDeviceObject , сначала принимаются драйвером фильтра, который обрабатывает их и перенаправляет к следующему драйверу в стеке, вызывая IoCallDriver.

Если объект устройства, указанный параметром TargetDevice , в настоящее время находится в верхней части стека драйверов, SourceDevice присоединяется непосредственно к TargetDevice. В этом случае TargetDevice и возвращенный указатель AttachedToDeviceObject равны.

Если один или несколько объектов устройства фильтра уже подключены над TargetDevice в стеке драйверов, IoAttachDeviceToDeviceStackSafe присоединяет SourceDevice к самому верхнему объекту устройства фильтра. Указатель на последний возвращается в AttachedToDeviceObject.

В момент сразу после присоединения к верхней части стека sourceDevice занимает верхнюю часть стека драйверов. Обратите внимание, что это не обязательно означает, что SourceDevice останется в верхней части стека драйверов. Другие фильтры могут присоединять собственные объекты устройства фильтра над SourceDevice в стеке.

IoAttachDeviceToDeviceStackSafe задает для элемента AlignmentRequirement объекта устройства, на который указывает SourceDevice , значение соответствующего в следующем объекте устройства ниже, а для stackSize в SourceDevice — значение в следующем и нижнем объекте плюс единица.

Требования

Требование	Значение
Минимальная версия клиента	Эта подпрограмма доступна в накопительном пакете обновления для Windows 2000 с пакетом обновления 4 (SP4), а также в Windows XP и более поздних версий.
Целевая платформа	Универсальное
Верхняя часть	ntddk.h (включая Ntddk.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDIS(storport)

См. также раздел

IoAttachDeviceToDeviceStack

IoCallDriver

Поделиться через