Controlling a General I/O Target's State in UMDF

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 framework defines the following states for general I/O targets:

Started
The I/O target is open (that is, available to the UMDF driver) and the driver can send I/O requests to it. The framework delivers the requests to the appropriate driver.

Stopped
The I/O target is open, but the UMDF driver cannot send I/O requests to the I/O target unless the driver passes the WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE flag to the Flags parameter in a call to the IWDFIoRequest::Send method.

The framework stops delivering requests to the appropriate driver.

Closed for Query-Remove
The I/O target is temporarily closed because its device might soon be removed.

Closed
The I/O target is closed and cannot be started or stopped.

Deleted
The I/O target's device has been removed.

The WDF_IO_TARGET_STATE enumeration defines the values that represent these states.

Local I/O Target States

The framework automatically opens and starts local I/O targets.

If necessary, the driver can call IWDFIoTargetStateManagement::Stop to temporarily stop a local I/O target and call IWDFIoTargetStateManagement::Start to restart it. For example, the driver might stop a local I/O target if it detects a temporary error condition and then restart the I/O target if the error condition is corrected.

If a local I/O target's device is removed, the framework automatically stops and closes the I/O target and cancels all I/O requests that are in the target's queue. The framework notifies the driver that the device is no longer available by calling device object event callback functions. For more information about these callback functions, see PnP and Power Management Scenarios in UMDF.

Drivers can call IWDFIoTargetStateManagement::GetState to obtain the current state of a local I/O target.

Remote I/O Target States

Drivers must call IWDFRemoteTarget::OpenFileByName or IWDFRemoteTarget::OpenRemoteInterface to open remote I/O targets. When a driver opens a remote I/O target, the framework automatically starts the I/O target.

If necessary, the driver can call IWDFRemoteTarget::Stop to temporarily stop a remote I/O target and call IWDFRemoteTarget::Start to restart it.

If a remote I/O target's device is removed, the framework automatically stops and closes the I/O target and cancels all I/O requests that are in the target's queue, unless the driver registers the following event callback functions:

IRemoteTargetCallbackRemoval::OnRemoteTargetQueryRemove
Informs the driver that a remote I/O target's device might be removed. Your driver must call IWDFRemoteTarget::CloseForQueryRemove if you want the driver to allow removal of the device.

IRemoteTargetCallbackRemoval::OnRemoteTargetRemoveComplete
Informs the driver that a remote I/O target's device has been removed. This callback function must call IWDFRemoteTarget::Close.

IRemoteTargetCallbackRemoval::OnRemoteTargetRemoveCanceled
Informs the driver that an attempt to remove a remote I/O target's device has been canceled. If you want the driver to continue to use the target, the driver must call IWDFRemoteTarget::Reopen. Typically, a driver calls Reopen from within the OnRemoteTargetRemoveCanceled callback function, but Reopen can instead be called after OnRemoteTargetRemoveCanceled returns.

Drivers can call IWDFRemoteTarget::GetState to obtain the current state of a remote I/O target.