Функция WdfIoTargetFormatRequestForRead (wdfiotarget.h)

Статья
08/08/2023

[Относится к KMDF и UMDF]

Метод WdfIoTargetFormatRequestForRead создает запрос на чтение для целевого объекта ввода-вывода, но не отправляет запрос.

Синтаксис

NTSTATUS WdfIoTargetFormatRequestForRead(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         OutputBuffer,
  [in, optional] PWDFMEMORY_OFFSET OutputBufferOffset,
  [in, optional] PLONGLONG         DeviceOffset
);

Параметры

[in] IoTarget

Дескриптор для локального или удаленного целевого объекта ввода-вывода, полученного при предыдущем вызове WdfDeviceGetIoTarget или WdfIoTargetCreate, или из метода, предоставленного специализированным целевым объектом ввода-вывода.

[in] Request

Дескриптор объекта запроса платформы. Дополнительные сведения см. в разделе "Примечания".

[in, optional] OutputBuffer

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

[in, optional] OutputBufferOffset

Указатель на структуру WDFMEMORY_OFFSET , выделенную вызывающим объектом, которая предоставляет необязательные значения смещения и длины байтов. Платформа использует эти значения для определения начального адреса и длины в выходном буфере для передачи данных. Если этот указатель имеет значение NULL, передача данных начинается в начале выходного буфера, а размер передачи равен размеру буфера.

[in, optional] DeviceOffset

Указатель на переменную, указывающую начальное смещение для передачи. Целевой объект ввода-вывода (т. е. драйвер следующего уровня ниже) определяет способ использования этого значения. Например, драйверы в стеке драйверов диска могут указывать смещение от начала диска. Целевой объект ввода-вывода получает эти сведения в элементе Parameters.Read.DeviceOffset структуры WDF_REQUEST_PARAMETERS запроса. Этот указатель является необязательным. Большинство драйверов устанавливают для этого указателя значение NULL.

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

WdfIoTargetFormatRequestForRead возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может вернуть одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_INVALID_DEVICE_REQUEST	Длина передачи была больше длины буфера, или запрос ввода-вывода уже был поставлен в очередь в целевой объект ввода-вывода.
STATUS_INSUFFICIENT_RESOURCES	Платформе не удалось выделить системные ресурсы (обычно это память).
STATUS_REQUEST_NOT_ACCEPTED	Пакет запроса ввода-вывода (IRP), который представляет параметр Request , не предоставляет достаточно IO_STACK_LOCATION структур, позволяющих драйверу пересылать запрос.

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Используйте метод WdfIoTargetFormatRequestForRead , а затем метод WdfRequestSend для синхронной или асинхронной отправки запросов на чтение. Кроме того, используйте метод WdfIoTargetSendReadSynchronously для синхронной отправки запросов на чтение.

Вы можете переслать запрос ввода-вывода, полученный драйвером в очереди ввода-вывода, или создать и отправить новый запрос. В любом случае для платформы требуется объект запроса и некоторое буферное пространство.

Чтобы переслать запрос ввода-вывода, полученный драйвером в очереди ввода-вывода, выполните приведенные далее действия.

Укажите дескриптор полученного запроса для параметра Request метода WdfIoTargetFormatRequestForRead.
Используйте выходной буфер полученного запроса для параметра OutputBuffer метода WdfIoTargetFormatRequestForRead.
Драйвер должен вызвать WdfRequestRetrieveOutputMemory , чтобы получить дескриптор объекта памяти платформы, который представляет выходной буфер запроса и должен использовать этот дескриптор в качестве значения для OutputBuffer.

Дополнительные сведения о переадресации запроса ввода-вывода см. в разделе Переадресация запросов ввода-вывода.

Драйверы часто делят полученные запросы ввода-вывода на небольшие запросы, отправляемые в целевой объект ввода-вывода, поэтому ваш драйвер может создавать новые запросы.

Чтобы создать новый запрос ввода-вывода, выполните приведенные далее действия.

Создайте новый объект запроса и укажите его дескриптор для параметра Request метода WdfIoTargetFormatRequestForRead.
Вызовите WdfRequestCreate , чтобы предварительно выделить один или несколько объектов запроса. Эти объекты запросов можно использовать повторно, вызвав WdfRequestReuse. Функция обратного вызова EvtDriverDeviceAdd вашего драйвера может предварительно выделить объекты запросов для устройства.
Укажите буферное пространство и укажите дескриптор буфера для параметра OutputBuffer метода WdfIoTargetFormatRequestForRead.
Драйвер должен указать это буферное пространство в качестве дескриптора WDFMEMORY для памяти, управляемой платформой. Драйвер может выполнять одно из следующих действий:
- Вызовите WdfMemoryCreate или WdfMemoryCreatePreallocated , чтобы создать буфер памяти, если требуется, чтобы драйвер передал новый буфер целевому объекту ввода-вывода.
- Вызовите WdfRequestRetrieveOutputMemory , чтобы получить дескриптор объекта памяти, представляющего буфер полученного запроса ввода-вывода, если требуется, чтобы драйвер передавал содержимое этого буфера целевому объекту ввода-вывода.
Обратите внимание, что если драйвер вызывает WdfRequestRetrieveOutputMemory и передает дескриптор памяти в WdfIoTargetFormatRequestForRead, драйвер не должен завершить полученный запрос ввода-вывода до тех пор, пока драйвер не удалит, повторно использует или переформатирует новый созданный драйвером объект запроса. (WdfIoTargetFormatRequestForRead увеличивает количество ссылок объекта памяти. Удаление, повторное использование или переформатирование объекта запроса уменьшает количество ссылок объекта памяти.)

Некоторые целевые объекты ввода-вывода принимают запросы на чтение с буфером нулевой длины. Для таких целевых объектов ввода-вывода драйвер может указать ЗНАЧЕНИЕ NULL для параметра OutputBuffer .

После того как драйвер вызывает WdfIoTargetFormatRequestForRead для форматирования запроса ввода-вывода, он должен вызвать WdfRequestSend для отправки запроса (синхронно или асинхронно) в целевой объект ввода-вывода.

Несколько вызовов WdfIoTargetFormatRequestForRead , использующих один и тот же запрос, не приводят к выделению дополнительных ресурсов. Таким образом, чтобы снизить вероятность того, что WdfRequestCreate вернет STATUS_INSUFFICIENT_RESOURCES, функция обратного вызова EvtDriverDeviceAdd драйвера может вызвать WdfRequestCreate для предварительного выделения одного или нескольких объектов запроса для устройства. Впоследствии драйвер может повторно использовать (вызвать WdfRequestReuse), переформатировать (вызвать WdfIoTargetFormatRequestForRead) и повторно отправить (вызвать WdfRequestSend) каждый объект запроса без риска STATUS_INSUFFICIENT_RESOURCES возвращаемого значения при последующем вызове WdfRequestCreate. Все последующие вызовы WdfIoTargetFormatRequestForRead для повторно использованного объекта запроса будут возвращать STATUS_SUCCESS, если значения параметров не изменяются. (Если драйвер не вызывает один и тот же метод форматирования запросов каждый раз, могут быть выделены дополнительные ресурсы.)

Сведения о получении сведений о состоянии после завершения запроса ввода-вывода см. в разделе Получение сведений о завершении.

Дополнительные сведения о WdfIoTargetFormatRequestForRead см. в разделе Отправка запросов ввода-вывода в общие целевые объекты ввода-вывода.

Дополнительные сведения о целевых объектах ввода-вывода см. в разделе Использование целевых объектов ввода-вывода.

Примеры

Следующий пример кода создает объект памяти платформы для выходного буфера запроса на чтение, форматирует запрос на чтение, регистрирует функцию обратного вызова CompletionRoutine и отправляет запрос на чтение целевому объекту ввода-вывода.

WDFREQUEST  request;
NTSTATUS  status;
WDFMEMORY  memory;
WDF_OBJECT_ATTRIBUTES  attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         DRIVER_TAG,
                         READ_BUF_SIZE,
                         &memory,
                         NULL
                         );

if (!NT_SUCCESS(status)) {
    return status;
}

status = WdfIoTargetFormatRequestForRead(
                                         IoTarget,
                                         request,
                                         memory,
                                         NULL,
                                         NULL
                                         );
if (!NT_SUCCESS(status)) {
        return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyReadRequestCompletionRoutine,
                               targetInfo
                               );
if (WdfRequestSend(
                   request,
                   IoTarget,
                   WDF_NO_SEND_OPTIONS
                   ) == FALSE) {
        status = WdfRequestGetStatus(request);
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfiotarget.h (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf)