WdfRequestSend 関数 (wdfrequest.h)

  • [アーティクル]

[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 構造体にタイムアウト値を設定し、この構造体の Flags メンバーのタイムアウト フラグを設定することをお勧めします。

ドライバーがタイムアウト値を提供する場合は、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
Header wdfrequest.h (Wdf.h を含む)
Library 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)

こちらもご覧ください

CompletionRoutine

WDF_REQUEST_SEND_OPTIONS

WdfDeviceGetIoTarget

WdfRequestAllocateTimer

WdfRequestCreate

WdfRequestGetStatus