WdfRequestRetrieveOutputBuffer 関数 (wdfrequest.h)

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

[KMDF と UMDF に適用]

WdfRequestRetrieveOutputBuffer メソッドは、I/O 要求の出力バッファーを取得します。

構文

NTSTATUS WdfRequestRetrieveOutputBuffer(
  [in]            WDFREQUEST Request,
  [in]            size_t     MinimumRequiredSize,
  [out]           PVOID      *Buffer,
  [out, optional] size_t     *Length
);

パラメーター

[in] Request

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

[in] MinimumRequiredSize

ドライバーが I/O 要求を処理するために必要な最小バッファーサイズ (バイト単位)。

[out] Buffer

バッファーのアドレスを受け取る場所へのポインター。

[out, optional] Length

バッファーのサイズをバイト単位で受け取る場所へのポインター。このパラメーターは省略可能であり、 NULL にすることができます。

戻り値

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

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

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

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

注釈

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

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

WdfRequestRetrieveOutputBuffer がSTATUS_SUCCESSを返した場合、ドライバーはアドレスと、必要に応じて出力バッファーのサイズを受け取ります。

ドライバーは、Request パラメーターが表す I/O 要求が完了するまで、取得したバッファーにアクセスできます。

WdfRequestRetrieveOutputBuffer を呼び出す代わりに、ドライバーは WdfRequestRetrieveOutputMemory を呼び出すことができます。これにより、バッファーを表すフレームワークメモリオブジェクトが作成されます。

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

例

次のコード例は、 EvtIoDeviceControl コールバック関数の一部です。この例では、USB デバイスの構成記述子を取得し、I/O 要求の出力バッファーに記述子を配置します。

VOID
MyEvtIoDeviceControl(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  OutputBufferLength,
    IN size_t  InputBufferLength,
    IN ULONG  IoControlCode    
    )
{
    WDFDEVICE  device;
    PDEVICE_CONTEXT  pDevContext;
    size_t  bytesReturned = 0;
    NTSTATUS  status;

    device = WdfIoQueueGetDevice(Queue);
    //
    // GetDeviceContext is a driver-defined function 
    // to retrieve device object context space.
    //
    pDevContext = GetDeviceContext(device);

    switch(IoControlCode) {

      case IOCTL_OSRUSBFX2_GET_CONFIG_DESCRIPTOR: {
 
        PUSB_CONFIGURATION_DESCRIPTOR  configurationDescriptor = NULL;
        USHORT  requiredSize;

        //
        // First, get the size of the USB configuration descriptor.
        //
        status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                                pDevContext->UsbDevice,
                                                NULL,
                                                &requiredSize
                                                );
        if (status == STATUS_BUFFER_TOO_SMALL) {
            break;
        }

        //
        // Get the buffer. Make sure the buffer is big
        // enough to hold the configuration descriptor.
        //
        status = WdfRequestRetrieveOutputBuffer(
                                                Request, 
                                                (size_t)requiredSize,
                                                &configurationDescriptor,
                                                NULL
                                                );
        if(!NT_SUCCESS(status)){
            break;
        }
        //
        // Now get the config descriptor.
        //
        status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                                pDevContext->UsbDevice,
                                                configurationDescriptor,
                                                &requiredSize
                                                );
        if (!NT_SUCCESS(status)) {
            break;
        }

        bytesReturned = requiredSize;
      }
        break;
...
    (Other case statements removed.)
...
    default:
        status = STATUS_INVALID_DEVICE_REQUEST;
        break;
    }
    //
    // Complete the request.
    //
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      bytesReturned
                                      );
    return;
}

要件

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

こちらもご覧ください

WdfRequestRetrieveInputBuffer

WdfRequestRetrieveOutputMemory

WdfRequestRetrieveOutputBuffer 関数 (wdfrequest.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース