WdfIoTargetFormatRequestForIoctl 函式 (wdfiotarget.h)
[適用於 KMDF 和 UMDF]
WdfIoTargetFormatRequestForIoctl 方法會建置 I/O 目標的裝置控制要求，但不會傳送要求。
語法
NTSTATUS WdfIoTargetFormatRequestForIoctl(
[in] WDFIOTARGET IoTarget,
[in] WDFREQUEST Request,
[in] ULONG IoctlCode,
[in, optional] WDFMEMORY InputBuffer,
[in, optional] PWDFMEMORY_OFFSET InputBufferOffset,
[in, optional] WDFMEMORY OutputBuffer,
[in, optional] PWDFMEMORY_OFFSET OutputBufferOffset
);
參數
[in] IoTarget
從先前呼叫 WdfDeviceGetIoTarget 或 WdfIoTargetCreate 取得的本機或遠端 I/O 目標物件的句柄，或從特製化 I/O 目標提供的方法取得。
[in] Request
架構要求物件的句柄。 如需詳細資訊，請參閱接下來的＜備註＞一節。
[in] IoctlCode
I/O 目標支援的 I/O 控制項程式代碼 (IOCTL) 。
[in, optional] InputBuffer
架構記憶體物件的句柄。 這個物件代表緩衝區，其中包含將傳送至 I/O 目標的數據。 如需詳細資訊，請參閱接下來的＜備註＞一節。
[in, optional] InputBufferOffset
呼叫端配置的 WDFMEMORY_OFFSET 結構的指標，可提供選擇性位元移和長度值。 架構會使用這些值來判斷數據傳輸的輸入緩衝區內的開始地址和長度。 如果此指標為 NULL，則數據傳輸會從輸入緩衝區的開頭開始，而傳輸大小則是緩衝區大小。
[in, optional] OutputBuffer
架構記憶體物件的句柄。 這個物件代表將從 I/O 目標接收數據的緩衝區。 如需詳細資訊，請參閱接下來的＜備註＞一節。
[in, optional] OutputBufferOffset
呼叫端配置的 WDFMEMORY_OFFSET 結構的指標，可提供選擇性位元移和長度值。 架構會使用這些值來判斷數據傳輸的輸出緩衝區內的開始地址和長度。 如果此指標為 NULL，數據傳輸會從輸出緩衝區的開頭開始，而傳輸大小則是緩衝區大小。
傳回值
如果作業成功，WdfIoTargetFormatRequestForIoctl 會傳回STATUS_SUCCESS。 否則，這個方法可能會傳回下列其中一個值：
| 傳回碼 | Description |
|---|---|
|
偵測到無效的參數。 |
|
傳輸長度大於緩衝區長度，或 I/O 要求已排入佇列至 I/O 目標。 |
|
架構無法配置系統資源 (通常是記憶體) 。 |
|
Request 參數所代表的 I/O 要求封包 (IRP) 沒有足夠的IO_STACK_LOCATION結構，可讓驅動程序轉送要求。 |
這個方法也可能傳回其他 NTSTATUS值。
如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。
備註
使用 WdfIoTargetFormatRequestForIoctl 方法，後面接著 WdfRequestSend 方法，以同步或異步方式傳送裝置控制要求。 或者，使用 WdfIoTargetSendIoctlSynchronously 方法來同步傳送裝置控制要求。
如需裝置控制要求的詳細資訊，請參閱 使用 I/O 控制程式碼。
您可以轉送驅動程式在 I/O 佇列中收到的裝置控制要求，也可以建立並傳送新的要求。 不論是哪一種情況，架構都需要要求物件和一些緩衝區空間。
若要轉送驅動程式在 I/O 佇列中收到的裝置控制要求：
- 為 WdfIoTargetFormatRequestForIoctl 方法的 Request 參數指定收到的要求句柄。
-
針對 WdfIoTargetFormatRequestForIoctl 方法的 InputBuffer 參數，使用收到的要求輸入緩衝區。
驅動程式必須呼叫 WdfRequestRetrieveInputMemory ，以取得代表要求輸入緩衝區之架構記憶體物件的句柄，而且必須使用該句柄做為 InputBuffer 的值。
-
針對 WdfIoTargetFormatRequestForIoctl 方法的 OutputBuffer 參數，使用收到的要求輸出緩衝區。
驅動程式必須呼叫 WdfRequestRetrieveOutputMemory 以取得要求的輸出緩衝區句柄，而且必須使用該句柄作為 OutputBuffer 的值。
驅動程式通常會將接收的 I/O 要求分成較小的要求，這些要求會傳送至 I/O 目標，因此您的驅動程式可能會建立新的要求。
若要建立新的 I/O 要求：
-
建立新的要求物件，並提供其 WdfIoTargetFormatRequestForIoctl 方法的 Request 參數句柄。
呼叫 WdfRequestCreate 以預先配置一或多個要求物件。 您可以藉由呼叫 WdfRequestReuse 來重複使用這些要求物件。 驅動程式的 EvtDriverDeviceAdd 回呼函式可以預先配置裝置的要求物件。
-
提供緩衝區空間，併為 WdfIoTargetFormatRequestForIoctl 方法的 InputBuffer 和 OutputBuffer 參數提供緩衝區的句柄。
您的驅動程式必須將此緩衝區空間指定為WDFMEMORY句柄給架構管理的記憶體。 您的驅動程式可以執行下列任一動作：
- 如果您想要驅動程式將新的緩衝區傳遞至 I/O 目標，請呼叫 WdfMemoryCreate 或 WdfMemoryCreatePreallocated 以建立新的記憶體緩衝區。
- 呼叫 WdfRequestRetrieveInputMemory 或 WdfRequestRetrieveOutputMemory ，以取得代表所接收 I/O 要求緩衝區之內存物件的句柄，如果您想要驅動程式將該緩衝區的內容傳遞至 I/O 目標。
使用相同要求的 WdfIoTargetFormatRequestForIoctl 多次呼叫並不會造成額外的資源配置。 因此，為了降低 WdfRequestCreate 將傳回STATUS_INSUFFICIENT_RESOURCES的機會，驅動程式的 EvtDriverDeviceAdd 回呼函式可以呼叫 WdfRequestCreate 來預先配置裝置的一或多個要求物件。 驅動程式後續可以重複使用 (呼叫 WdfRequestReuse) 、重新格式化 (呼叫 WdfIoTargetFormatRequestForIoctl) ，然後重新傳送 (呼叫 WdfRequestSend) 每個要求物件，而不需在稍後呼叫 WdfRequestCreate 時產生STATUS_INSUFFICIENT_RESOURCES傳回值的風險。 如果參數值未變更，則針對重複使用的要求物件對 WdfIoTargetFormatRequestForIoctl 的所有後續呼叫都會傳回STATUS_SUCCESS。 (如果驅動程式每次都未呼叫相同的要求格式方法，可能會配置其他資源。此外，如果 I/O 控制程式代碼 指定METHOD_BUFFERED的傳輸類型，則架構必須為每個要求配置系統緩衝區，且該配置可能會因為記憶體資源不足而失敗。)
如需在 I/O 要求完成之後取得狀態資訊的相關信息，請參閱 取得完成資訊。
如需 WdfIoTargetFormatRequestForIoctl 的詳細資訊，請參閱 將 I/O 要求傳送至一般 I/O 目標。
如需 I/O 目標的詳細資訊，請參閱 使用 I/O 目標。
範例
下列程式代碼會重複使用預先配置的要求物件和預先配置的記憶體物件。 此範例會將輸入和輸出緩衝區指派給記憶體物件、格式化要求對象、註冊 CompletionRoutine 回呼函式，並將要求傳送至 I/O 目標。
NTSTATUS
NICSendOidRequestToTargetAsync(
IN WDFIOTARGET IoTarget,
IN WDFREQUEST Request,
IN PFILE_OBJECT FileObject,
IN ULONG IoctlControlCode,
IN OUT PVOID InputBuffer,
IN ULONG InputBufferLength,
IN OUT PVOID OutputBuffer,
IN ULONG OutputBufferLength,
OUT PULONG BytesReadOrWritten
)
{
NTSTATUS status;
PREQUEST_CONTEXT reqContext;
WDF_REQUEST_REUSE_PARAMS params;
WDFMEMORY inputMem, outputMem;
WDF_REQUEST_REUSE_PARAMS_INIT(
¶ms,
WDF_REQUEST_REUSE_NO_FLAGS,
STATUS_SUCCESS
);
status = WdfRequestReuse(Request, ¶ms);
if (!NT_SUCCESS(status)){
return status;
}
reqContext = GetRequestContext(Request);
inputMem = outputMem = NULL;
if (InputBuffer != NULL) {
status = WdfMemoryAssignBuffer(
reqContext->InputMemory,
InputBuffer,
InputBufferLength
);
if (!NT_SUCCESS(status)) {
return status;
}
inputMem = reqContext->InputMemory;
}
if (OutputBuffer != NULL) {
status = WdfMemoryAssignBuffer(
reqContext->OutputMemory,
OutputBuffer,
OutputBufferLength
);
if (!NT_SUCCESS(status)) {
return status;
}
outputMem = reqContext->OutputMemory;
}
status = WdfIoTargetFormatRequestForIoctl(
IoTarget,
Request,
IoctlControlCode,
inputMem,
NULL,
outputMem,
NULL
);
if (!NT_SUCCESS(status)) {
return status;
}
WdfRequestSetCompletionRoutine(
Request,
NICSendOidRequestToTargetAsyncCompletionRoutine,
BytesReadOrWritten
);
if (WdfRequestSend(
Request,
IoTarget,
WDF_NO_SEND_OPTIONS
) == FALSE) {
status = WdfRequestGetStatus(Request);
}
return status;
}
規格需求
| 需求 | 值 |
|---|---|
| 目標平台 | 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) |
另請參閱
WdfIoTargetFormatRequestForInternalIoctl
WdfIoTargetSendIoctlSynchronously