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
指定了不正確記憶體描述元、管道的類型無效、傳輸方向無效,或指定的 I/O 要求已排入 I/O 目標佇列。
STATUS_INTEGER_OVERFLOW
Offset參數指定的位移無效。
STATUS_REQUEST_NOT_ACCEPTED
Request參數所代表的 I/O 要求封包 (IRP) 沒有足夠的IO_STACK_LOCATION結構,可讓驅動程式轉送要求。
 

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

如果驅動程式提供不正確物件控制碼,就會發生錯誤檢查。

備註

使用 WdfUsbTargetPipeFormatRequestForWrite,後面接著 WdfRequestSend,以同步或非同步方式傳送寫入要求。 或者,使用 WdfUsbTargetPipeWriteSynchronously 方法來同步傳送寫入要求。

指定的管道必須是輸出管道,而管道 的類型 必須是 WdfUsbPipeTypeBulkWdfUsbPipeTypeInterrupt

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

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

  1. WdfUsbTargetPipeFormatRequestForWrite 方法的 Request 參數指定收到的要求控制碼。
  2. 針對 WdfUsbTargetPipeFormatRequestForWrite 方法的 WriteMemory 參數,使用收到的要求輸入緩衝區。

    驅動程式必須呼叫 WdfRequestRetrieveInputMemory ,以取得架構記憶體物件的控制碼,該物件代表要求的輸入緩衝區,並使用該控制碼做為 WriteMemory的值。

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

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

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

  1. 建立新的要求物件,並為 WdfUsbTargetPipeFormatRequestForWrite 方法的 Request 參數提供其控制碼。

    呼叫 WdfRequestCreate 以預先配置一或多個要求物件。 您可以藉由呼叫 WdfRequestReuse來重複使用這些要求物件。 驅動程式的 EvtDriverDeviceAdd 回呼函式可以預先配置裝置的要求物件。

  2. 提供緩衝區空間,並為 WdfUsbTargetPipeFormatRequestForWrite 方法的 WriteMemory 參數提供緩衝區的控制碼。

    您的驅動程式必須將此緩衝區空間指定為架構管理的記憶體的 WDFMEMORY 控制碼。 您的驅動程式可以執行下列任一動作:

    • 如果您想要驅動程式將新的緩衝區傳遞至 I/O 目標,請呼叫 WdfMemoryCreateWdfMemoryCreatePreallocated 以建立新的記憶體緩衝區。
    • 如果您想要讓驅動程式將該緩衝區的內容傳遞至 I/O 目標,請呼叫 WdfRequestRetrieveInputMemory 以取得代表所接收 I/O 要求緩衝區的記憶體物件的控制碼。
    請注意,如果您的驅動程式呼叫 WdfRequestRetrieveInputMemory 並將記憶體控制碼傳遞至 WdfUsbTargetPipeFormatRequestForWrite,則驅動程式必須等到驅動程式刪除、重複使用或重新格式化新的驅動程式建立要求物件之後,才能完成收到的 I/O 要求。 (WdfUsbTargetPipeFormatRequestForWrite 會遞增記憶體物件的參考計數。刪除、重複使用或重新格式化要求物件會遞減記憶體物件的參考計數。)
呼叫 WdfUsbTargetPipeFormatRequestForWrite 來格式化 I/O 要求之後,驅動程式必須呼叫 WdfRequestSend ,以同步或非同步方式) 將要求傳送至 I/O 目標 (。

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

如需在 I/O 要求完成之後取得狀態資訊的相關資訊,請參閱 取得完成資訊

如需 WdfUsbTargetPipeFormatRequestForWrite 方法和 USB I/O 目標的詳細資訊,請參閱 USB I/O 目標

範例

下列程式碼範例來自 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 (包含 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