WDF_DEVICE_IO_BUFFER_RETRIEVAL enumeration (wudfddi_types.h)

Article
02/22/2024

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

The WDF_DEVICE_IO_BUFFER_RETRIEVAL enumeration is used to specify when UMDF makes an I/O request's buffers available to the driver.

Syntax

typedef enum _WDF_DEVICE_IO_BUFFER_RETRIEVAL {
  WdfDeviceIoBufferRetrievalInvalid,
  WdfDeviceIoBufferRetrievalCopyImmediately,
  WdfDeviceIoBufferRetrievalDeferred,
  WdfDeviceIoBufferRetrievalMaximum
} WDF_DEVICE_IO_BUFFER_RETRIEVAL, *PWDF_DEVICE_IO_BUFFER_RETRIEVAL;

Constants


`WdfDeviceIoBufferRetrievalInvalid` Reserved for system use.
`WdfDeviceIoBufferRetrievalCopyImmediately` UMDF makes an I/O request's buffers available to the driver (by copying them into the UMDF driver host process) as soon as UMDF receives the I/O request. For more information, see the following Remarks section.
`WdfDeviceIoBufferRetrievalDeferred` UMDF makes an I/O request's buffers available to the driver (by copying them into the UMDF driver host process) only when the driver attempts to access the buffers. For more information, see the following Remarks section.
`WdfDeviceIoBufferRetrievalMaximum` Reserved for system use.

Remarks

The WDF_DEVICE_IO_BUFFER_RETRIEVAL enumeration is used as input to IWDFDeviceInitialize2::SetIoTypePreference.

In UMDF versions prior to version 1.9, UMDF always makes an I/O request's buffers available to the driver (by copying the buffers into the UMDF driver host process) as soon as UMDF receives the I/O request. IWDFIoRequest::GetInputMemory and IWDFIoRequest::GetOutputMemory are the only object methods that drivers can call to access the buffers.

UMDF versions 1.9 and later can support either immediate or deferred retrieval of request buffers. All new drivers should enable deferred retrieval because it usually provides better driver performance than immediate retrieval. If a driver does not enable deferred retrieval, UMDF uses immediate retrieval.

To defer retrieval of buffers, your driver must call IWDFDeviceInitialize2::SetIoTypePreference and specify the WdfDeviceIoBufferRetrievalDeferred value. After your driver enables deferred retrieval, it can call the following methods to access request buffers, using either the buffered or direct access method:

IWDFIoRequest2::RetrieveInputBuffer

IWDFIoRequest2::RetrieveInputMemory

IWDFIoRequest2::RetrieveOutputBuffer

IWDFIoRequest2::RetrieveOutputMemory

A driver that enables deferred retrieval cannot use IWDFIoRequest::GetInputMemory and IWDFIoRequest::GetOutputMemory to access the buffers.

For more information about accessing an I/O request's data buffers, see Accessing Data Buffers in UMDF-Based Drivers.