WdfRequestSend 関数 (wdfrequest.h)

[アーティクル]
02/07/2025

[KMDF と UMDF に適用]

WdfRequestSend メソッドは、指定した I/O 要求を指定した I/O ターゲットに送信します。

構文

BOOLEAN WdfRequestSend(
  [in] WDFREQUEST                Request,
  [in] WDFIOTARGET               Target,
       PWDF_REQUEST_SEND_OPTIONS Options
);

パラメーター

[in] Request

フレームワーク要求オブジェクトへのハンドル。

[in] Target

フレームワーク I/O ターゲットオブジェクトへのハンドル。このハンドルを取得する方法の詳細については、次の「解説」セクションを参照してください。

Options

呼び出し元が指定した要求オプションを含む WDF_REQUEST_SEND_OPTIONS 構造体へのポインター。このパラメーターは省略可能であり、要求オプションを有効にしない場合は NULL をできます。

戻り値

WdfRequestSend は、要求がターゲットに送信された場合 TRUE を返します。それ以外の場合、このメソッドは FALSE 返し、WdfRequestGetStatus 呼び出 は、NT_SUCCESS() テストに失敗した状態を返します。

ドライバーが無効なオブジェクトハンドルを提供すると、バグチェックが発生します。

備考

Request パラメーターに対してドライバーが指定する要求オブジェクトには、受け取った要求オブジェクトと、WdfRequestCreate メソッドを呼び出して作成した要求オブジェクトを指定できます。

I/O ターゲットオブジェクトへのハンドルを取得するには、ドライバーは、次のいずれかを実行できます。

ドライバーが一般的な I/O ターゲットを使用している場合は、WdfDeviceGetIoTargetを呼び出します。詳細については、「一般的な I/O ターゲットの初期化」を参照してください。
ドライバーが特殊化された I/O ターゲットを使用している場合は、特殊化されたターゲットオブジェクトが定義する 1 つ以上のメソッドを呼び出します。たとえば、USB デバイスのドライバーは、WdfUsbTargetDeviceGetIoTarget 呼び出したり、WdfUsbTargetPipeGetIoTarget をしたりすることができます。

既定では、WdfRequestSend は、要求を非同期的にターゲットに配信します。つまり、要求が完了するのを待たずに直ちに返されます。必要に応じて、要求を同期的に配信できます。つまり、WdfRequestSend は、ドライバーが要求を完了するまで戻りません。要求を同期的に送信するには、ドライバーは、WDF_REQUEST_SEND_OPTIONS 構造体で WDF_REQUEST_SEND_OPTION_SYNCHRONOUS フラグを設定する必要があります。

WdfRequestSend 失敗した場合、またはドライバーが WDF_REQUEST_SEND_OPTION_SYNCHRONOUS フラグを設定した場合、ドライバーは、WdfRequestSendを呼び出した直後に、WdfRequestGetStatus を呼び出すことができます。

WdfRequestSend 成功し、ドライバーが WDF_REQUEST_SEND_OPTION_SYNCHRONOUS フラグを設定していない場合、ドライバーは通常、CompletionRoutine コールバック関数内から WdfRequestGetStatus を呼び出します。

ドライバーが同期的に要求を送信する場合は、ドライバーが WDF_REQUEST_SEND_OPTIONS 構造体にタイムアウト値を設定し、この構造体のメンバーフラグのタイムアウトフラグを設定することをお勧めします。

ドライバーがタイムアウト値を提供する場合は、WdfRequestSend を呼び出す前に、WdfRequestAllocateTimer呼び出す必要があります。これにより、タイマーを割り当てるのに十分なシステムリソースがない場合、WdfRequestSend は失敗しません。

ドライバーが WDF_REQUEST_SEND_OPTION_SYNCHRONOUS フラグを設定する場合は、IRQL = PASSIVE_LEVEL で WdfRequestSend を呼び出す必要があります。このフラグが設定されていない場合、ドライバーは IRQL <= DISPATCH_LEVELでこのメソッドを呼び出す必要があります。 WdfRequestSend 、呼び出し元の IRQL で要求を送信します。

ドライバーは、WdfRequestSend を呼び出して USB パイプに I/O 要求を送信することはできません。ドライバーがパイプの連続リーダーを構成している場合。

UMDF ドライバーに要求を送信する場合、カーネルモードドライバーは、「UMDF ドライバーでの Kernel-Mode クライアントのサポートで説明されている IRQL 制限に従う必要があります。

WdfRequestSendの詳細については、「転送 I/O 要求」を参照してください。

例

次のコード例は、kmdf_fx2 サンプルドライバーからの EvtIoWrite コールバック関数の短縮バージョンです。この関数は、要求のバッファー長を検証し、バッファーへのハンドルを取得し、USB ターゲットの要求を書式設定して、要求を送信します。

VOID 
OsrFxEvtIoWrite(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    WDFUSBPIPE  pipe;
    NTSTATUS  status;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;

    UNREFERENCED_PARAMETER(Queue);
    //
    // Check if the transfer size is valid.
    //
    if (Length > MAX_TRANSFER_BUFFER_SIZE) {
        status = STATUS_INVALID_PARAMETER;
        goto Exit;
    }
    //
    // Get driver-defined context space from
    // the device object. The driver stored the
    // pipe handle there.
    //
    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
    pipe = pDeviceContext->BulkWritePipe;
 
    //
    // Get a handle to a memory object that represents
    // the input buffer.
    //
    status = WdfRequestRetrieveInputMemory(Request, &reqMemory);
    if (!NT_SUCCESS(status)){
        goto Exit;
    }
    //
    // Format the request so it can be sent to a USB target.
    //
    status = WdfUsbTargetPipeFormatRequestForWrite(
                            pipe,
                            Request,
                            reqMemory,
                            NULL // Offsets
                            ); 
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    //
    // Set a CompletionRoutine callback function.
    //
    WdfRequestSetCompletionRoutine(
                            Request,
                            EvtRequestReadCompletionRoutine,
                            pipe
                            );
    //
    // Send the request. If an error occurs, complete the request.
    //
    if (WdfRequestSend(
                       Request,
                       WdfUsbTargetPipeGetIoTarget(pipe),
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
        goto Exit;
    }
Exit:
    if (!NT_SUCCESS(status)) {
        WdfRequestCompleteWithInformation(
                                          Request,
                                          status,
                                          0
                                          );
    }
    return;
}

必要条件

要件	価値
ターゲットプラットフォームの	万国
最小 KMDF バージョン	1.0
UMDF の最小バージョンをする	2.0
ヘッダー	wdfrequest.h (Wdf.h を含む)
ライブラリ	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	「解説」セクションを参照してください。
DDI コンプライアンス規則をする	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), ReqCompletionRoutine(kmdf), ReqMarkCancelableSend(kmdf), ReqSendFail(kmdf), ReqSendWhileSpinlock(kmdf), RequestCompleted(kmdf)RequestCompletedLocal(kmdf), RequestFormattedValid(kmdf), RequestGetStatusValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), SyncReqSend2(kmdf), WdfRequestSendSyncAtDispatch(kmdf), WdfRequestSendSyncAtDispatch2(kmdf)

次の方法で共有

WdfRequestSend 関数 (wdfrequest.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース