WDF_DEVICE_IO_BUFFER_RETRIEVAL enumeration

[Applies to UMDF 1.x only]

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          = 0x00,
  WdfDeviceIoBufferRetrievalCopyImmediately  = 0x01,
  WdfDeviceIoBufferRetrievalDeferred         = 0x02,
  WdfDeviceIoBufferRetrievalMaximum          = 0x3
} 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.

Requirements

End of support

Unavailable in UMDF 2.0 and later.

Minimum UMDF version

1.9

Header

Wudfddi_types.h (include Wudfddi.h)

See also

WDF_DEVICE_IO_TYPE (UMDF)

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft