Specifying a Callback Synchronization Mode

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.

The archived UMDF 1 samples can be found in the Windows 11, version 22H2 - May 2022 Driver Samples Update.

For more info, see Getting Started with UMDF.

The driver can specify how its callback functions are called by the framework. The driver specifies a synchronization (or locking) mode for a device before it calls the IWDFDriver::CreateDevice method to create a device object for the device. To specify synchronization mode, the driver should call the IWDFDeviceInitialize::SetLockingConstraint method. The driver receives a pointer to the IWDFDeviceInitialize interface when its IDriverEntry::OnDeviceAdd method is called to add the device to the system.

The driver can specify one of the following values from the WDF_CALLBACK_CONSTRAINT enumeration type in the LockType parameter of IWDFDeviceInitialize::SetLockingConstraint to identify the locking mode. The type of constraint (or locking) specified depends on how much parallelism the hardware device can exploit and how much the driver can handle.

Value	Meaning
None (0)	Indicates that no callback functions into the driver are synchronized.
WdfDeviceLevel (1)	Indicates that all queue callback functions into the driver are synchronized.

Note   If the driver does not call IWDFDeviceInitialize::SetLockingConstraint to specify a value, the framework sets the default value of this property to WdfDeviceLevel.

Constraints apply only to queue callback functions and not to Plug and Play (PnP) and power management callback functions. Queue callback functions include the following:

• Automatic dispatch callback functions, such as, IQueueCallbackRead::OnRead and IQueueCallbackWrite::OnWrite. For more information, see I/O Queue Event Callback Functions.

• Queue state change callback functions, such as, IQueueCallbackStateChange::OnStateChange.

• Request cancellation callback functions, such as, IRequestCallbackCancel::OnCancel.

• File cleanup and close callback functions, such as, IFileCallbackCleanup::OnCleanupFile and IFileCallbackClose::OnCloseFile.

Request completion callback functions (IRequestCallbackRequestCompletion::OnCompletion) are not queue callback functions. Therefore, they are not synchronized.