IWDFDeviceInitialize2::SetIoTypePreference method (wudfddi.h)

Artikel
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 SetIoTypePreference method specifies your preferences for how UMDF and the driver access the data buffers of a device's I/O requests.

Syntax

void SetIoTypePreference(
  [in] WDF_DEVICE_IO_BUFFER_RETRIEVAL RetrievalMode,
  [in] WDF_DEVICE_IO_TYPE             ReadWritePreference,
  [in] WDF_DEVICE_IO_TYPE             IoControlPreference
);

Parameters

[in] RetrievalMode

A WDF_DEVICE_IO_BUFFER_RETRIEVAL-typed value that specifies the buffer retrieval mode that you prefer UMDF to use to make an I/O request's buffers available to the driver.

[in] ReadWritePreference

A WDF_DEVICE_IO_TYPE-typed value that specifies the buffer access method that you prefer UMDF to use for the data buffers of read and write requests.

[in] IoControlPreference

A WDF_DEVICE_IO_TYPE-typed value that specifies the buffer access method that you prefer UMDF to use for the data buffers of device I/O control requests.

Return value

None

Remarks

If a driver calls SetIoTypePreference for a device, it must do so from its IDriverEntry::OnDeviceAdd callback function, before the driver calls IWDFDriver::CreateDevice.

If the driver does not call SetIoTypePreference, UMDF sets the RetrievalMode parameter to WdfDeviceIoBufferRetrievalCopyImmediately and it sets the buffer access method to WdfDeviceIoBuffered for read, write, and device I/O control requests.

UMDF might not use the preferences that the driver specifies when it calls SetIoTypePreference. For more information about how UMDF chooses a retrieval mode and buffer access method, see Specifying a Buffer Retrieval Mode and How UMDF Chooses a Buffer Access Method for an I/O Request.

A driver cannot set the buffer access method to WdfDeviceIoDirect or WdfDeviceIoBufferedOrDirect unless it also sets the RetrievalMode parameter to WdfDeviceIoBufferRetrievalDeferred.

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

Examples

The following code example shows a segment of a driver's IDriverEntry::OnDeviceAdd callback function. The segment obtains the IWDFDeviceInitialize2 interface and then calls SetIoTypePreference.

HRESULT
 CMyDriver::OnDeviceAdd(
    __in IWDFDriver *FxWdfDriver,
    __in IWDFDeviceInitialize *FxDeviceInit
    )
{
...
    //
    // Declare an IWDFDeviceInitialize2 interface pointer and obtain the
    // IWDFDeviceInitialize2 interface from the IWDFDeviceInitialize interface.
    //
    CComQIPtr<IWDFDeviceInitialize2> di2 = FxDeviceInit;

    //
    // For this device, set the retrieval mode to deferred, set
    // the access method to buffered for read and write requests,
    // and set the access mode to direct for device I/O control requests.
    // 
    di2->SetIoTypePreference(WdfDeviceIoBufferRetrievalDeferred,
                             WdfDeviceIoBuffered,
                             WdfDeviceIoDirect);
...
}

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.9
Header	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Delen via