WdfUsbTargetPipeFormatRequestForRead 函式 (wdfusb.h)

發行項
02/29/2024

[適用於 KMDF 和 UMDF]

WdfUsbTargetPipeFormatRequestForRead 方法會建置 USB 輸入管道的讀取要求，但不會傳送要求。

語法

NTSTATUS WdfUsbTargetPipeFormatRequestForRead(
  [in]           WDFUSBPIPE        Pipe,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         ReadMemory,
  [in, optional] PWDFMEMORY_OFFSET ReadOffset
);

參數

[in] Pipe

呼叫 WdfUsbInterfaceGetConfiguredPipe 取得之架構管道物件的句柄。

[in] Request

架構要求物件的句柄。如需詳細資訊，請參閱接下來的＜備註＞一節。

[in, optional] ReadMemory

架構記憶體物件的句柄。這個物件代表將從管道接收數據的緩衝區。除非驅動程式呼叫 WdfUsbTargetPipeSetNoMaximumPacketSizeCheck，否則緩衝區大小必須是管道最大封包大小的倍數。如需此緩衝區的詳細資訊，請參閱下列一節。

[in, optional] ReadOffset

呼叫端配置的 WDFMEMORY_OFFSET 結構的指標，可提供選擇性的位元移和長度值。架構會使用這些值來判斷數據傳輸之讀取緩衝區內的起始位址和長度。如果此指標為 NULL，則數據傳輸會從緩衝區的開頭開始，而傳輸大小則是緩衝區大小。

傳回值

如果作業成功，WdfUsbTargetPipeFormatRequestForRead 會傳回STATUS_SUCCESS。否則，此方法可以傳回下列其中一個值：

傳回碼	Description
STATUS_INVALID_PARAMETER	偵測到無效的參數。
STATUS_INSUFFICIENT_RESOURCES	記憶體不足。
STATUS_INVALID_DEVICE_REQUEST	指定了無效的記憶體描述元、管道的類型無效、傳輸方向無效，或指定的 I/O 要求已排入 I/O 目標佇列。
STATUS_INTEGER_OVERFLOW	指定 Offset 參數無效的位移。
STATUS_INVALID_BUFFER_SIZE	緩衝區大小不是管道封包大小上限的倍數。除非驅動程式呼叫 WdfUsbTargetPipeSetNoMaximumPacketSizeCheck，否則緩衝區大小必須是管道最大封包大小的倍數。
STATUS_REQUEST_NOT_ACCEPTED	要求參數所代表的 I/O 要求封包 (IRP) 沒有足夠的IO_STACK_LOCATION結構，可讓驅動程式轉送要求。

這個方法也可能傳回其他 NTSTATUS值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

使用 WdfUsbTargetPipeFormatRequestForRead，後面接著 WdfRequestSend，以同步或異步方式傳送讀取要求。或者，使用 WdfUsbTargetPipeReadSynchronously 方法來同步傳送讀取要求。

Pipe 參數指定的管道必須是輸入管道，而管道的類型必須是 WdfUsbPipeTypeBulk 或 WdfUsbPipeTypeInterrupt。

您可以轉送驅動程式在 I/O 佇列中收到的 I/O 要求，也可以建立並傳送新的要求。不論是哪一種情況，架構都需要要求物件和一些緩衝區空間。

若要轉送驅動程式在 I/O 佇列中收到的 I/O 要求：

為 WdfUsbTargetPipeFormatRequestForRead 方法的 Request 參數指定收到的要求句柄。
針對 WdfUsbTargetPipeFormatRequestForRead 方法的 ReadMemory 參數，使用收到的要求輸出緩衝區。
驅動程式必須呼叫 WdfRequestRetrieveOutputMemory ，以取得架構記憶體物件的句柄，此物件代表要求的輸出緩衝區，並使用該句柄做為 ReadMemory 參數的值。

如需轉送 I/O 要求的詳細資訊，請參閱轉送 I/O 要求。

驅動程式通常會將收到的 I/O 要求分成較小的要求，這些要求會傳送至 I/O 目標，因此您的驅動程式可能會建立新的要求。

若要建立新的 I/O 要求：

建立新的要求物件，併為 WdfUsbTargetPipeFormatRequestForRead 方法的 Request 參數提供其句柄。
呼叫 WdfRequestCreate 以預先配置一或多個要求物件。您可以呼叫 WdfRequestReuse 來重複使用這些要求物件。驅動程式的 EvtDriverDeviceAdd 回呼函式可以預先配置裝置的要求物件。
提供緩衝區空間，並提供 WdfUsbTargetPipeFormatRequestForRead 方法的 ReadMemory 參數的緩衝區句柄。
您的驅動程式必須將此緩衝區空間指定為架構管理的記憶體的WDFMEMORY句柄。您的驅動程式可以執行下列其中一項：
- 如果您想要驅動程式將新的緩衝區傳遞至 I/O 目標，請呼叫 WdfMemoryCreate 或 WdfMemoryCreatePreallocated 來建立新的記憶體緩衝區。
- 如果您想要讓驅動程式將該緩衝區的內容傳遞至 I/O 目標，請呼叫 WdfRequestRetrieveOutputMemory 以取得代表已接收 I/O 要求的緩衝區內存物件的句柄。
請注意，如果您的驅動程式呼叫 WdfRequestRetrieveOutputMemory 並將記憶體句柄傳遞至 WdfUsbTargetPipeFormatRequestForRead，在驅動程式刪除、重複使用或重新格式化新的驅動程式建立要求物件之前，驅動程式不得完成收到的 I/O 要求。 (WdfUsbTargetPipeFormatRequestForRead 會遞增記憶體對象的參考計數。刪除、重複使用或重新格式化要求物件會遞減記憶體對象的參考計數。)

呼叫 WdfUsbTargetPipeFormatRequestForRead 以格式化 I/O 要求之後，驅動程式必須呼叫 WdfRequestSend ，以同步或異步方式將要求傳送) 至 I/O 目標 (。

使用相同要求的 WdfUsbTargetPipeFormatRequestForRead 多次呼叫並不會造成額外的資源配置。因此，為了減少 WdfRequestCreate 將傳回STATUS_INSUFFICIENT_RESOURCES的機會，驅動程式的 EvtDriverDeviceAdd 回呼函式可以呼叫 WdfRequestCreate 來預先配置裝置的一或多個要求物件。驅動程式後續可以重複使用 (呼叫 WdfRequestReuse) 、重新格式化 (呼叫 WdfUsbTargetPipeFormatRequestForRead) ，然後重新傳送 (呼叫 WdfRequestSend) 每個要求物件，而不會有STATUS_INSUFFICIENT_RESOURCES從稍後呼叫 WdfRequestCreate 傳回值的風險。如果參數值未變更，則針對重複使用的要求物件，對 WdfUsbTargetPipeFormatRequestForRead 的所有後續呼叫都會傳回STATUS_SUCCESS。 (如果驅動程式每次未呼叫相同的要求格式方法，可能會配置其他資源。)

架構會在其內部 URB 中設定USBD_SHORT_TRANSFER_OK旗標。設定此旗標可讓數據傳輸的最後一個封包小於封包大小上限。

如需 I/O 要求完成之後取得狀態資訊的相關信息，請參閱取得完成資訊。

如需 WdfUsbTargetPipeFormatRequestForRead 方法和 USB I/O 目標的詳細資訊，請參閱 USB I/O 目標。

範例

下列程式代碼範例來自 kmdf_fx2 範例驅動程式。此範例是 EvtIoRead 回呼函式，會將讀取要求轉送至 USB 管道。此範例會呼叫 WdfRequestRetrieveOutputMemory 以取得要求的輸出緩衝區，然後將讀取要求格式化，以便將要求傳送至 USB 管道。接下來，此範例會註冊 CompletionRoutine 回呼函式。最後，它會將要求傳送至USB管道。

VOID 
OsrFxEvtIoRead(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    WDFUSBPIPE  pipe;
    NTSTATUS  status;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;

    //
    // First, validate input parameters.
    //
    if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
        status = STATUS_INVALID_PARAMETER;
        goto Exit;
    }

    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
 
    pipe = pDeviceContext->BulkReadPipe;
 
    status = WdfRequestRetrieveOutputMemory(
                                            Request,
                                            &reqMemory
                                            );
    if (!NT_SUCCESS(status)){
        goto Exit;
    }
 
    status = WdfUsbTargetPipeFormatRequestForRead(
                                                  pipe,
                                                  Request,
                                                  reqMemory,
                                                  NULL
                                                  ); 
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }

    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestReadCompletionRoutine,
                                   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;
}

規格需求

需求	值
目標平台	Universal
最小 KMDF 版本	1.0
最低UMDF版本	2.0
標頭	wdfusb.h (包含 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)