WdfRequestCreate 関数 (wdfrequest.h)

[アーティクル]
02/27/2024

[KMDF と UMDF に適用]

WdfRequestCreate メソッドは、空のフレームワーク要求オブジェクトを作成します。

構文

NTSTATUS WdfRequestCreate(
  [in, optional] PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in, optional] WDFIOTARGET            IoTarget,
  [out]          WDFREQUEST             *Request
);

パラメーター

[in, optional] RequestAttributes

要求オブジェクトのオブジェクト属性を指定する呼び出し元によって割り当てられた WDF_OBJECT_ATTRIBUTES 構造体へのポインター。このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。

[in, optional] IoTarget

フレームワーク I/O ターゲットオブジェクトへのハンドル。このパラメーターは省略可能であり、 NULL にすることができます。 NULL 以外の場合、WdfRequestCreate は、ドライバーが最終的に指定された I/O ターゲットに要求を送信できることを確認します。

[out] Request

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

戻り値

WdfRequestCreate は、操作が成功した場合にSTATUS_SUCCESSを返します。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_PARAMETER	入力パラメーターが無効です。
STATUS_INSUFFICIENT_RESOURCES	操作を完了するのに十分なシステムリソースがありません。
STATUS_REQUEST_NOT_ACCEPTED	要求の I/O スタックの場所の配列は、ドライバーが指定した I/O ターゲットに要求を送信するのに十分な大きさではありません。

その他の戻り値の一覧については、「 Framework オブジェクト作成エラー」を参照してください。

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

注釈

フレームワークベースのドライバーは 、WdfRequestCreate を呼び出して、ドライバーが初期化のために他のフレームワーク関数に渡す新しい要求を作成できます。たとえば、USB デバイスのドライバーが WdfUsbTargetPipeFormatRequestForRead を呼び出して、新しい読み取り要求を書式設定する場合があります。

WDM ドライバーと通信するフレームワークベースのドライバーでは、 WdfRequestCreateFromIrp を呼び出すことによって要求の内容を指定できます。

ドライバーが WdfRequestCreate を呼び出して要求オブジェクトを作成する場合、要求オブジェクトに対して WdfRequestComplete を呼び出してはなりません。代わりに、要求オブジェクトの使用が完了したら、ドライバーは WdfObjectDelete を呼び出す必要があります。詳細については、「 I/O 要求の完了」を参照してください。

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

WdfRequestCreate の呼び出しの詳細については、「Framework 要求オブジェクトの作成」を参照してください。

例

次のコード例では、I/O ターゲットオブジェクトを作成し、 WDF_OBJECT_ATTRIBUTES 構造体を初期化し、 WdfRequestCreate を呼び出します。新しい要求オブジェクトの親は、I/O ターゲットオブジェクトです。

WDF_OBJECT_ATTRIBUTES  attributes;
WDFREQUEST newRequest;
WDFIOTARGET ioTarget;
...
status = WdfIoTargetCreate(
                           Device,
                           WDF_NO_OBJECT_ATTRIBUTES,
                           &ioTarget
                           );
  ...
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = ioTarget;

status = WdfRequestCreate(
                          &attributes,
                          ioTarget,
                          &newRequest
                          );

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

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	wdfrequest.h (Wdf.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf)、 InvalidReqAccessLocal(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 ReqDelete(kmdf)、 RequestForUrbXrb(kmdf)、 RequestSendAndForgetNoFormatting2(kmdf)