Функция WdfIoTargetFormatRequestForRead (wdfiotarget.h)
[Относится к 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, если операция выполнена успешно. В противном случае этот метод может вернуть одно из следующих значений:
Код возврата | Описание |
---|---|
|
Обнаружен недопустимый параметр. |
|
Длина передачи была больше длины буфера, или запрос ввода-вывода уже был поставлен в очередь в целевой объект ввода-вывода. |
|
Платформе не удалось выделить системные ресурсы (обычно это память). |
|
Пакет запроса ввода-вывода (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 , чтобы получить дескриптор объекта памяти, представляющего буфер полученного запроса ввода-вывода, если требуется, чтобы драйвер передавал содержимое этого буфера целевому объекту ввода-вывода.
После того как драйвер вызывает 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) |
См. также раздел
WdfIoTargetFormatRequestForWrite
WdfIoTargetSendReadSynchronously