WdfRequestRetrieveOutputMemory 関数 (wdfrequest.h)

  • [アーティクル]

[KMDF と UMDF に適用]

WdfRequestRetrieveOutputMemory メソッドは、I/O 要求の出力バッファーを表すフレームワーク メモリ オブジェクトへのハンドルを取得します。

構文

NTSTATUS WdfRequestRetrieveOutputMemory(
  [in]  WDFREQUEST Request,
  [out] WDFMEMORY  *Memory
);

パラメーター

[in] Request

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

[out] Memory

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

戻り値

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

リターン コード 説明
STATUS_INVALID_PARAMETER
 入力パラメーターが無効です。
STATUS_INVALID_DEVICE_REQUEST
 要求の種類が無効であるか、要求で バッファーされた I/O も直接 I/O も使用されていません。 データ バッファーにアクセスするためのサポートされているメソッドの詳細については、次の「解説」セクションを参照してください。
STATUS_INTERNAL_ERROR
 要求は既に完了しています。
STATUS_BUFFER_TOO_SMALL
 出力バッファーの長さは 0 です。
STATUS_INSUFFICIENT_RESOURCES
 メモリが不足しています。
 

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

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

注釈

要求の出力バッファーは、ドライバーが要求の発信元に提供する情報 (ディスクからのデータなど) を受け取ります。 ドライバーは WdfRequestRetrieveOutputMemory を呼び出して、読み取り要求またはデバイス I/O 制御要求の出力バッファーを取得できますが、書き込み要求では取得できません (書き込み要求では出力データが提供されないため)。

WdfRequestRetrieveOutputMemory メソッドは、バッファー化された I/O メソッドまたはデータ バッファーにアクセスするための直接 I/O メソッドを使用する I/O 要求の出力バッファーを取得します。 要求の I/O 制御コードが IRP_MJ_INTERNAL_DEVICE_CONTROLされている場合、または要求が別のカーネル モード ドライバーから送信された場合、 WdfRequestRetrieveOutputMemory では 、バッファーされた I/O も直接 I/O も使用しない I/O 要求もサポートされます。

WdfRequestRetrieveOutputMemory がSTATUS_SUCCESSを返す場合、ドライバーは出力バッファーを表すフレームワーク メモリ オブジェクトへのハンドルを受け取ります。 バッファーにアクセスするには、ドライバーは WdfMemoryGetBuffer を呼び出す必要があります。

ドライバーは、Request パラメーターが表す I/O 要求が完了するまで、取得したフレームワーク メモリ オブジェクトにアクセスできます。

WdfRequestRetrieveOutputMemory を呼び出す代わりに、ドライバーは、バッファーのアドレスと長さを取得する WdfRequestRetrieveOutputBuffer を呼び出すことができます。

WdfRequestRetrieveOutputMemory の詳細については、「Framework-Based ドライバーでのデータ バッファーへのアクセス」を参照してください。

例

次のコード例は、 EvtIoRead コールバック関数が、読み取り要求の出力バッファーを表すフレームワーク メモリ オブジェクトへのハンドルを取得する方法を示しています。 次に、読み取り要求の書式を設定し、USB I/O ターゲットに送信します。

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

    //
    // The driver previously stored a pipe handle in 
    // the device object's context space.
    //
    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
    pipe = pDeviceContext->BulkReadPipe;

    //
    // Get output memory.
    //
    status = WdfRequestRetrieveOutputMemory(
                                            Request,
                                            &reqMemory
                                            );
    if(!NT_SUCCESS(status)){
        goto Exit;
    }
    //
    // Format the request.
    //
    status = WdfUsbTargetPipeFormatRequestForRead(
                                           pipe,
                                           Request,
                                           reqMemory,
                                           NULL
                                           ); 
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestReadCompletionRoutine,
                                   pipe
                                   );
    //
    // Send the request.
    //
    if (WdfRequestSend(
                       Request,
                       WdfUsbTargetPipeGetIoTarget(pipe),
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
        goto Exit;
    }
Exit:
    //
    // Complete the request now if an error occurred.
    //
    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 <=DISPATCH_LEVEL
DDI コンプライアンス規則 DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)、 MemAfterReqCompletedIntIoctl(kmdf)、 MemAfterReqCompletedIntIoctlA(kmdf)、 MemAfterReqCompletedIoctl(kmdf)、 MemAfterReqCompletedIoctlA(kmdf)、 MemAfterReqCompletedRead(kmdf)、 MemAfterReqCompletedReadA(kmdf)、 MemAfterReqCompletedWrite(kmdf), OutputBufferAPI(kmdf)

こちらもご覧ください

WdfMemoryGetBuffer

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputBuffer