WdfRequestCreateFromIrp 関数 (wdfrequest.h)

[アーティクル]
08/08/2023

[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

WDM I/O 要求パケットを含む IRP 構造体へのポインター。

[in] RequestFreesIrp

TRUE の場合、要求ハンドルが破棄されたときにフレームワークによって IRP が削除されることを示すブール値。 FALSE の場合、ドライバーは、次の例のセクションで示す手順を使用して、IRP を削除する IoFreeIrp を呼び出す必要があります。

[out] Request

フレームワーク要求オブジェクトへのハンドルを受け取る場所へのポインター。

戻り値

操作が成功した場合、WdfRequestCreateFromIrp はSTATUS_SUCCESSを返します。その他の戻り値の一覧については、「フレームワークオブジェクト作成エラー」を参照してください。

このメソッドは、他の NTSTATUS 値も返す場合があります。

注釈

通常、フレームワークベースのドライバーは、WDM ディスパッチルーチンで WDM IRP を受信し、フレームワーク I/O ターゲットに要求を転送する場合にのみ、 WdfRequestCreateFromIrp を呼び出します。

ドライバーが WdfRequestCreateFromIrp を呼び出して要求オブジェクトを作成する場合、要求オブジェクトに対して WdfRequestComplete を呼び出してはなりません。代わりに、ドライバーは要求オブジェクトの使用が完了したときに WdfObjectDelete を呼び出す必要があります。

さらに、ドライバーは、新しい要求オブジェクトで WdfRequestRetrieveOutputMemory、 WdfRequestRetrieveOutputBuffer、 WdfRequestRetrieveInputBuffer、または WdfRequestRetrieveInputMemory を呼び出してはなりません。

既定では、新しい要求オブジェクトの親は、WdfDriverCreate メソッドによって作成されたフレームワークドライバーオブジェクトです。 WDF_OBJECT_ATTRIBUTES構造体の ParentObject メンバーを使用して、別の親を指定できます。フレームワークは、親オブジェクトを削除すると、要求オブジェクトを削除します。ドライバーが既定の親を変更しない場合、ドライバーは、オブジェクトの使用が完了したときに要求オブジェクトを削除する必要があります。それ以外の場合、要求オブジェクトは、I/O マネージャーがドライバーをアンロードするまで残ります。

フレームワーク要求オブジェクトの作成の詳細については、「 Framework 要求オブジェクトの作成」を参照してください。

フレームワークベースのドライバーでは、このメンバーを使用するため、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);

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
Header	wdfrequest.h (Wdf.h を含む)
Library	Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)