共用方式為


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

從先前呼叫 WdfDeviceGetIoTargetWdfIoTargetCreate 取得的本機或遠端 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
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值

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

備註

使用 WdfIoTargetFormatRequestForIoctl 方法,後面接著 WdfRequestSend 方法,以同步或異步方式傳送裝置控制要求。 或者,使用 WdfIoTargetSendIoctlSynchronously 方法來同步傳送裝置控制要求。

如需裝置控制要求的詳細資訊,請參閱 使用 I/O 控制程式碼

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

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

  1. WdfIoTargetFormatRequestForIoctl 方法的 Request 參數指定收到的要求句柄。
  2. 針對 WdfIoTargetFormatRequestForIoctl 方法的 InputBuffer 參數,使用收到的要求輸入緩衝區。

    驅動程式必須呼叫 WdfRequestRetrieveInputMemory ,以取得代表要求輸入緩衝區之架構記憶體物件的句柄,而且必須使用該句柄做為 InputBuffer 的值。

  3. 針對 WdfIoTargetFormatRequestForIoctl 方法的 OutputBuffer 參數,使用收到的要求輸出緩衝區。

    驅動程式必須呼叫 WdfRequestRetrieveOutputMemory 以取得要求的輸出緩衝區句柄,而且必須使用該句柄作為 OutputBuffer 的值。

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

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

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

  1. 建立新的要求物件,並提供其 WdfIoTargetFormatRequestForIoctl 方法的 Request 參數句柄。

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

  2. 提供緩衝區空間,併為 WdfIoTargetFormatRequestForIoctl 方法的 InputBufferOutputBuffer 參數提供緩衝區的句柄。

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

    請注意,如果您的驅動程式呼叫 WdfRequestRetrieveInputMemoryWdfRequestRetrieveOutputMemory ,並將記憶體句柄傳遞至 WdfIoTargetFormatRequestForIoctl,則驅動程式在驅動程式刪除、重複使用或重新格式化新的驅動程式建立要求物件之前,不得完成收到的 I/O 要求。 (WdfIoTargetFormatRequestForIoctl 遞增記憶體對象的參考計數。刪除、重複使用或重新格式化要求物件會遞減記憶體對象的參考計數。)
在驅動程式呼叫 WdfIoTargetFormatRequestForIoctl 來格式化裝置控制項要求之後,驅動程式必須呼叫 WdfRequestSend ,以同步或異步方式) 將要求傳送至 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(
                                  &params, 
                                  WDF_REQUEST_REUSE_NO_FLAGS, 
                                  STATUS_SUCCESS
                                  );
    status = WdfRequestReuse(Request, &params);
    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)

另請參閱

EvtDriverDeviceAdd

WDFMEMORY_OFFSET

WdfDeviceGetIoTarget

WdfIoTargetCreate

WdfIoTargetFormatRequestForInternalIoctl

WdfIoTargetSendIoctlSynchronously

WdfMemoryCreate

WdfMemoryCreatePreallocated

WdfRequestCreate

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputMemory

WdfRequestReuse

WdfRequestSend