Функция IoBuildSynchronousFsdRequest (wdm.h)

Статья
08/08/2023

Подпрограмма IoBuildSynchronousFsdRequest выделяет и настраивает IRP для синхронно обрабатываемого запроса ввода-вывода.

Синтаксис

__drv_aliasesMem PIRP IoBuildSynchronousFsdRequest(
  [in]           ULONG            MajorFunction,
  [in]           PDEVICE_OBJECT   DeviceObject,
  [in, out]      PVOID            Buffer,
  [in, optional] ULONG            Length,
  [in, optional] PLARGE_INTEGER   StartingOffset,
  [in]           PKEVENT          Event,
  [out]          PIO_STATUS_BLOCK IoStatusBlock
);

Параметры

[in] MajorFunction

Основной код функции для IRP. Этот код может быть IRP_MJ_PNP, IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_FLUSH_BUFFERS или IRP_MJ_SHUTDOWN.

[in] DeviceObject

Указатель на структуру DEVICE_OBJECT для объекта устройства следующего нижнего драйвера, представляющего целевое устройство.

[in, out] Buffer

Указатель на буфер данных. Если majorFunctionIRP_MJ_WRITE, буфер содержит данные для записи. Если majorFunctionIRP_MJ_READ, буфер получает данные. Если majorFunctionимеет значение IRP_MJ_FLUSH_BUFFERS или IRP_MJ_SHUTDOWN, этот параметр должен иметь значение NULL.

[in, optional] Length

Длина (в байтах) буфера, на который указывает buffer. Для таких устройств, как диски, это значение должно быть целым числом, кратным размеру сектора. Начиная с Windows 8, размер сектора может составлять 4096 или 512 байт. В более ранних версиях Windows размер сектора всегда составляет 512 байт. Этот параметр является обязательным для запросов на чтение и запись, но должен быть равен нулю для запросов на очистку и завершение работы.

[in, optional] StartingOffset

Указатель на смещение на диске для запросов на чтение и запись. Единицы измерения и значение этого значения зависят от драйвера. Этот параметр является обязательным для запросов на чтение и запись, но должен быть равен нулю для запросов на очистку и завершение работы.

[in] Event

Указатель на выделенный вызывающим объектом и инициализированный объект события. Диспетчер ввода-вывода устанавливает для события состояние Signaled , когда драйвер нижнего уровня завершает запрошенную операцию. После вызова IoCallDriver драйвер может ожидать объекта события.

[out] IoStatusBlock

Указатель на расположение, которое получает блок состояния ввода-вывода, заданный при завершении IRP драйвером более низкого уровня.

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

Если операция выполнена успешно, IoBuildSynchronousFsdRequest возвращает указатель на инициализированную структуру IRP с расположением стека ввода-вывода следующего ниже драйвера, настроенного на основе предоставленных параметров. В противном случае подпрограмма возвращает значение NULL.

Драйвер файловой системы (FSD) или другой драйвер более высокого уровня может вызывать IoBuildSynchronousFsdRequest для настройки irP, которые синхронно отправляются в драйверы более низкого уровня.

IoBuildSynchronousFsdRequest выделяет и настраивает IRP, который запрашивает драйверы более низкого уровня для выполнения синхронных операций чтения, записи, очистки или завершения работы. IRP содержит достаточно сведений для запуска операции.

Низкоуровневые драйверы могут накладывать ограничения на параметры, предоставляемые этой подпрограмме. Например, для драйверов дисков может потребоваться, чтобы значения length и StartingOffset были целыми числами, кратными размеру сектора устройства.

После вызова IoBuildSynchronousFsdRequest для создания запроса драйвер должен вызвать IoCallDriver , чтобы отправить запрос следующему драйверу ниже. Если IoCallDriver возвращает STATUS_PENDING, драйвер должен дождаться завершения IRP, вызвав KeWaitForSingleObject для заданного события. Большинству драйверов не нужно задавать подпрограмму IoCompletion для IRP.

IrP, созданные IoBuildSynchronousFsdRequest , должны быть завершены вызовом драйвера IoCompleteRequest. Драйвер, вызывающий IoBuildSynchronousFsdRequest , не должен вызывать IoFreeIrp, так как диспетчер ввода-вывода освобождает эти синхронные IRP после вызова IoCompleteRequest .

IoBuildSynchronousFsdRequest помещает создаваемые им irP в очередь IRP, относяющуюся к текущему потоку. Если поток завершается, диспетчер ввода-вывода отменяет IRP.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 2000.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Правила соответствия DDI	ForwardedAtBadIrqlFsdSync(wdm), HwStorPortProhibitedDDIs(storport), IoBuildSynchronousFsdRequestNoFree(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm)