WdfRequestCreateFromIrp 函式 (wdfrequest.h)

發行項
02/29/2024

[僅適用於 KMDF]

WdfRequestCreateFromIrp 方法會從指定的 WDM IRP 建立架構要求物件。

語法

NTSTATUS WdfRequestCreateFromIrp(
  [in, optional] PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in]           PIRP                   Irp,
  [in]           BOOLEAN                RequestFreesIrp,
  [out]          WDFREQUEST             *Request
);

參數

[in, optional] RequestAttributes

呼叫端配置的 WDF_OBJECT_ATTRIBUTES 結構的指標，指定要求對象的物件屬性。此參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。

[in] Irp

IRP 結構的指標，其中包含 WDM I/O 要求封包。

[in] RequestFreesIrp

布爾值，如果為 TRUE，表示架構會在要求句柄終結時移除 IRP。如果 為 FALSE，驅動程式必須呼叫 IoFreeIrp 來移除 IRP，並使用下列範例一節所示範的步驟。

[out] Request

接收架構要求物件句柄的位置指標。

傳回值

如果作業成功，WdfRequestCreateFromIrp 會傳回STATUS_SUCCESS。如需其他傳回值的清單，請參閱 Framework 物件建立錯誤。

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

備註

一般而言，架構型驅動程式只有在 WDM 分派例程中收到 WDM IRP，然後將要求轉送至架構 I/O 目標時，才會呼叫 WdfRequestCreateFromIrp 。

如果驅動程式呼叫 WdfRequestCreateFromIrp 來建立要求物件，它不得呼叫要求物件的 WdfRequestComplete 。相反地，驅動程式在使用要求物件完成時，必須呼叫 WdfObjectDelete 。

此外，驅動程式不得使用新的要求物件呼叫 WdfRequestRetrieveOutputMemory、 WdfRequestRetrieveOutputBuffer、 WdfRequestRetrieveInputBuffer 或 WdfRequestRetrieveInputMemory 。

根據預設，新要求物件的父系是 WdfDriverCreate 方法建立的架構驅動程序物件。您可以使用 WDF_OBJECT_ATTRIBUTES 結構的 ParentObject 成員來指定不同的父代。架構會在刪除父物件時刪除要求物件。如果您的驅動程式未變更預設父代，則驅動程式應該在使用物件完成時刪除要求物件;否則，要求物件會保留，直到 I/O 管理員卸除驅動程序為止。

如需建立架構要求對象的詳細資訊，請參閱建立架構要求物件。

架構型驅動程式不得使用 IRP 結構的 Tail.Overlay.DriverContext 成員，因為架構會使用此成員。

範例

範例 1

下列程式代碼範例會從指定的 WDM IRP 建立架構要求對象，然後刪除它。本範例會將 RequestFreesIrp 參數設定為 TRUE，因此架構會在要求句柄終結時移除 IRP。

WDFREQUEST request;
PIRP irp;

//Creation
status = WdfRequestCreateFromIrp(
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 irp,
                                 TRUE,
                                 &request
                                 );
...
//Deletion
WdfObjectDelete(request);

範例 2

下列程式代碼範例也會從指定的 WDM IRP 建立架構要求對象，然後刪除它。本範例會將 RequestFreesIrp 參數設定為 FALSE，因此驅動程式必須呼叫 IoFreeIrp 來移除 IRP。範例中的所有函式呼叫都是必要的。

WDF_REQUEST_REUSE_PARAMS params;
WDFREQUEST request;
PIRP irp;

//Creation
status = WdfRequestCreateFromIrp(
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 irp,
                                 FALSE,
                                 &request
                                 );
...
//Deletion
WDF_REQUEST_REUSE_PARAMS_INIT(
                              &params,
                              WDF_REQUEST_REUSE_NO_FLAGS,
                              STATUS_SUCCESS
                              );
WDF_REQUEST_REUSE_PARAMS_SET_NEW_IRP(
                                     &params,
                                     NULL
                                     );
status = WdfRequestReuse(
                         request,
                         &params
                         );
ASSERT(NT_SUCCESS(status));
IoFreeIrp(irp);
WdfObjectDelete(request);

規格需求

需求	值
目標平台	Universal
最小 KMDF 版本	1.0
標頭	wdfrequest.h (包含 Wdf.h)
程式庫	Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)