Edit

Share via

Controlling a General I/O Target's State

  • Article

You can visualize I/O target objects as having two gates: an in-gate and an out-gate. The out-gate controls when the framework delivers a request to the target device object, while the in-gate controls when a request is allowed to enter the I/O target at all.

The framework defines the following states for general I/O targets:

Started
Both gates of the I/O target object are open. The driver can send I/O requests to the I/O target queue, and the framework delivers the requests to the appropriate driver.

Stopped
The in-gate of the I/O target is open, but the out-gate is closed. The framework stops delivering requests to the appropriate driver. To send I/O requests to the I/O target, the driver must set either WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE or WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET in each request's WDF_REQUEST_SEND_OPTIONS structure.

Purged
Both gates of the I/O target object are closed. The driver cannot send I/O requests to the I/O target unless it sets WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE or WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET. In addition, the framework cancels unprocessed requests in the I/O target object's internal queue. This state is available beginning in KMDF version 1.11.

Closed for Query-Remove
A remote 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. Your driver can call WdfIoTargetGetState to obtain an I/O target's state.

Local I/O Target States

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

If necessary, the driver can call WdfIoTargetStop to temporarily stop a local I/O target and call WdfIoTargetStart 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.

In KMDF version 1.11 and later, the driver can call WdfIoTargetPurge to temporarily prevent I/O requests from being sent to a local I/O target, and to cancel unprocessed requests in the target's queue. For example, as part of file handle cleanup, a driver might purge a local I/O target to ensure that all requests sent to the driver are cancelled.

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.

Remote I/O Target States

Drivers must call WdfIoTargetOpen 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 WdfIoTargetStop to temporarily stop a remote I/O target and call WdfIoTargetStart to restart it.

In KMDF version 1.11 and later, the driver can call WdfIoTargetPurge to temporarily prevent I/O requests from being sent to a remote I/O target, and to cancel unprocessed requests in the target's queue.

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:

EvtIoTargetQueryRemove
Informs the driver that a remote I/O target's device might be removed. Your driver must call WdfIoTargetCloseForQueryRemove if you want the driver to allow removal of the device.

EvtIoTargetRemoveComplete
Informs the driver that a remote I/O target's device has been removed. This callback function must call WdfIoTargetClose.

EvtIoTargetRemoveCanceled
Informs the driver that an attempt to remove a remote I/O target's device has been canceled. This callback function must call WdfIoTargetOpen, and the driver typically calls WDF_IO_TARGET_OPEN_PARAMS_INIT_REOPEN to initialize its WDF_IO_TARGET_OPEN_PARAMS_INIT function.

If a driver has finished using a remote I/O target and will not use the target again, and the target has no child request objects that are still pending, the driver can call WdfObjectDelete without first calling WdfIoTargetClose. If the target has any child request objects that are still pending, the driver must call WdfIoTargetClose before it can safely call WdfObjectDelete.