WdfIoTargetFormatRequestForWrite 函式 (wdfiotarget.h)

發行項
02/27/2024

[適用於 KMDF 和 UMDF]

WdfIoTargetFormatRequestForWrite 方法會建置 I/O 目標的寫入要求，但不會傳送要求。

語法

NTSTATUS WdfIoTargetFormatRequestForWrite(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         InputBuffer,
  [in, optional] PWDFMEMORY_OFFSET InputBufferOffset,
  [in, optional] PLONGLONG         DeviceOffset
);

參數

[in] IoTarget

從先前呼叫 WdfDeviceGetIoTarget 或 WdfIoTargetCreate 取得的本機或遠端 I/O 目標物件的句柄，或從特製化 I/O 目標提供的方法取得。

[in] Request

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

[in, optional] InputBuffer

架構記憶體物件的句柄。這個物件代表緩衝區，其中包含將傳送至 I/O 目標的數據。這個參數是選擇性的，而且可以是 NULL。如需此參數的詳細資訊，請參閱下列一節。

[in, optional] InputBufferOffset

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

[in, optional] DeviceOffset

指定傳輸起始位移之位置的指標。 I/O 目標 (，也就是下一個較低的驅動程式) 會定義如何使用此值。例如，磁碟驅動程式堆疊中的驅動程式可能會指定磁碟開頭的位移。 I/O 目標會在要求WDF_REQUEST_PARAMETERS結構的 Parameters.Write.DeviceOffset 成員中取得這項資訊。此指標是選擇性的。大部分驅動程式都會將此指標設定為 NULL。

傳回值

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

傳回碼	Description
STATUS_INVALID_PARAMETER	偵測到無效的參數。
STATUS_INVALID_DEVICE_REQUEST	傳輸長度大於緩衝區長度，或 I/O 要求已排入佇列至 I/O 目標。
STATUS_INSUFFICIENT_RESOURCES	架構無法配置系統資源 (通常是記憶體) 。
STATUS_REQUEST_NOT_ACCEPTED	Request 參數所代表的 I/O 要求封包 (IRP) 沒有足夠的IO_STACK_LOCATION結構，可讓驅動程序轉送要求。

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

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

備註

使用 WdfIoTargetFormatRequestForWrite 方法，後面接著 WdfRequestSend 方法，以同步或異步方式傳送寫入要求。或者，使用 WdfIoTargetSendWriteSynchronously 方法來同步傳送寫入要求。

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

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

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

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

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

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

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

某些 I/O 目標接受具有零長度緩衝區的寫入要求。針對這類 I/O 目標，您的驅動程式可以為 InputBuffer 參數指定 NULL。

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

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

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

如需 WdfIoTargetFormatRequestForWrite 的詳細資訊，請參閱將 I/O 要求傳送至一般 I/O 目標。

如需 I/O 目標的詳細資訊，請參閱使用 I/O 目標。

範例

下列程式代碼範例會為寫入要求的輸入緩衝區建立架構記憶體物件、格式化寫入要求、註冊 CompletionRoutine 回呼函式，並將寫入要求傳送至 I/O 目標。

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

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

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

status = WdfIoTargetFormatRequestForWrite(
                                          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);
}

規格需求

需求	值
目標平台	Universal
最低 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)