Функция WdfUsbTargetPipeFormatRequestForWrite (wdfusb.h)

[Применимо к KMDF и UMDF]

Метод WdfUsbTargetPipeFormatRequestForWrite создает запрос на запись для выходного канала USB, но не отправляет запрос.

Синтаксис

NTSTATUS WdfUsbTargetPipeFormatRequestForWrite(
  [in]           WDFUSBPIPE        Pipe,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         WriteMemory,
  [in, optional] PWDFMEMORY_OFFSET WriteOffset
);

Параметры

[in] Pipe

Дескриптор объекта канала платформы, полученный путем вызова WdfUsbInterfaceGetConfiguredPipe.

[in] Request

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

[in, optional] WriteMemory

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

[in, optional] WriteOffset

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

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

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

Код возврата Описание
STATUS_INVALID_PARAMETER
Обнаружен недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES
Недостаточно памяти.
STATUS_INVALID_DEVICE_REQUEST
Указан недопустимый дескриптор памяти, недопустимый тип канала, направление передачи было недопустимым или указанный запрос ввода-вывода уже поставлен в очередь в целевой объект ввода-вывода.
STATUS_INTEGER_OVERFLOW
Недопустимое смещение, указанное параметром Offset .
STATUS_REQUEST_NOT_ACCEPTED
Пакет запроса ввода-вывода (IRP), который представляет параметр request , не предоставляет достаточно IO_STACK_LOCATION структур, чтобы разрешить драйверу пересылать запрос.
 

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

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

Комментарии

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

Указанный канал должен быть выходным каналом, а тип канала должен быть WdfUsbPipeTypeBulk или WdfUsbPipeTypeInterrupt.

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

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

  1. Укажите дескриптор полученного запроса для параметра Request метода Request метода WdfUsbTargetPipeFormatRequestForWrite.
  2. Используйте входной буфер полученного запроса для параметра WriteMemory метода WdfUsbTargetPipeFormatRequestForWrite.

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

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

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

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

  1. Создайте объект запроса и укажите его дескриптор для параметра Request метода WdfUsbTargetPipeFormatRequestForWrite.

    Вызовите WdfRequestCreate, чтобы предварительно выделить один или несколько объектов запроса. Эти объекты запроса можно использовать повторно, вызвав WdfRequestReuse. Функция обратного вызова EvtDriverDeviceAdd драйвера может предварительно выделить объекты запроса для устройства.

  2. Укажите буферное пространство и укажите дескриптор буфера для параметра WriteMemory метода WdfUsbTargetPipeFormatRequestForWrite.

    Драйвер должен указать это буферное пространство как дескриптор WDFMEMORY для управляемой платформой памяти. Драйвер может выполнить одно из следующих действий:

    • Вызовите WdfMemoryCreate или WdfMemoryCreatePreallocated, чтобы создать новый буфер памяти, если требуется, чтобы драйвер передал новый буфер в целевой объект ввода-вывода.
    • Вызовите WdfRequestRetrieveInputMemory, чтобы получить дескриптор объекта памяти, представляющего буфер полученного запроса ввода-вывода, если требуется, чтобы драйвер передал содержимое этого буфера в целевой объект ввода-вывода.
    Обратите внимание, что если драйвер вызывает WdfRequestRetrieveInputMemory и передает дескриптор памяти WdfUsbTargetPipeFormatRequestForWrite, драйвер не должен завершить полученный запрос ввода-вывода, пока драйвер не будет удален, повторно использует или переформатирует новый созданный драйвером объект запроса. (WdfUsbTargetPipeFormatRequestForWrite увеличивает количество ссылок объекта памяти. Удаление, повторное использование или переформатирование объекта запроса уменьшает количество ссылок объекта памяти.)
После вызова WdfUsbTargetPipeFormatRequestForWrite для форматирования запроса ввода-вывода драйвер должен вызвать WdfRequestSend для отправки запроса (синхронно или асинхронно) в целевой объект ввода-вывода.

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

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

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

Примеры

В следующем примере кода используется пример драйвера kmdf_fx2 . В этом примере показана функция обратного вызова EvtIoWrite , которая перенаправляет запрос на запись в USB-канал. В примере вызывается WdfRequestRetrieveInputMemory для получения входного буфера запроса, а затем он форматирует запрос на запись, чтобы запрос можно было отправить в USB-канал. Далее в примере регистрируется функция обратного вызова CompletionRoutine . Наконец, он отправляет запрос в USB-канал.

VOID 
OsrFxEvtIoWrite(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    NTSTATUS  status;
    WDFUSBPIPE  pipe;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;
 
    if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
        status = STATUS_INVALID_PARAMETER;
        goto Exit;
    }

    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
 
    pipe = pDeviceContext->BulkWritePipe;

    status = WdfRequestRetrieveInputMemory(
                                           Request,
                                           &reqMemory
                                           );
    if (!NT_SUCCESS(status)){
        goto Exit;
    }

    status = WdfUsbTargetPipeFormatRequestForWrite(
                                                   pipe,
                                                   Request,
                                                   reqMemory,
                                                   NULL
                                                   );
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }

    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestWriteCompletionRoutine,
                                   pipe
                                   );

    if (WdfRequestSend(
                       Request,
                       WdfUsbTargetPipeGetIoTarget(pipe),
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
        goto Exit;
    }

Exit:
    if (!NT_SUCCESS(status)) {
        WdfRequestCompleteWithInformation(
                                          Request,
                                          status,
                                          0
                                          );
    }
    return;
}

Требования

   
Целевая платформа Универсальное
Минимальная версия KMDF 1,0
Минимальная версия UMDF 2,0
Заголовок wdfusb.h (include Wdfusb.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), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

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

WdfUsbTargetPipeFormatRequestForRead