Hardware Dev Center

IWDFDeviceInitialize2::SetIoTypePreference method

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

RetrievalMode [in]

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.

ReadWritePreference [in]

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.

IoControlPreference [in]

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

Target platform

Desktop

End of support

Unavailable in UMDF 2.0 and later.

Minimum UMDF version

1.9

Header

Wudfddi.h (include Wudfddi.h)

DLL

WUDFx.dll

See also

IWDFDeviceInitialize2
IWDFIoRequest2::GetEffectiveIoType
WDF_DEVICE_IO_BUFFER_RETRIEVAL
WDF_DEVICE_IO_TYPE (UMDF)
WdfDeviceInitSetIoTypeEx
WdfDeviceInitSetIoType

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft