WdfRequestRetrieveOutputBuffer 関数 (wdfrequest.h)

[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を返します。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

このメソッドは、他の 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;
}

要件

こちらもご覧ください

WdfRequestRetrieveInputBuffer

WdfRequestRetrieveOutputMemory