WdfIoTargetStop function (wdfiotarget.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfIoTargetStop method stops sending queued requests to a local or remote I/O target.

Syntax

void WdfIoTargetStop(
  [in] WDFIOTARGET                  IoTarget,
  [in] WDF_IO_TARGET_SENT_IO_ACTION Action
);

Parameters

[in] IoTarget

A handle to a local or remote I/O target object that was obtained from a previous call to WdfDeviceGetIoTarget or WdfIoTargetCreate, or from a method that a specialized I/O target supplies.

[in] Action

A WDF_IO_TARGET_SENT_IO_ACTION-typed value that specifies how the framework should handle I/O requests that the driver has sent to the I/O target, if the target has not completed the requests.

Return value

None

Remarks

A bug check occurs if the driver supplies an invalid object handle.

If your driver can detect recoverable device errors, you might want your driver to call WdfIoTargetStop to temporarily stop sending requests, then later call WdfIoTargetStart to resume sending requests.

While stopped, an I/O target continues to accept new requests but does not deliver the queued requests to the appropriate driver.

For more information about possible states for I/O targets, see Controlling a General I/O Target's State.

If a driver calls WdfUsbTargetPipeConfigContinuousReader to configure a continuous reader for a USB pipe, the driver's EvtDeviceD0Exit callback function must call WdfIoTargetStop to stop the reader.

If a driver has called WdfIoTargetStop, it can still send a request to the target by setting the WDF_REQUEST_OPTION_IGNORE_TARGET_STATE flag in the request's WDF_REQUEST_SEND_OPTIONS structure. If a driver sets this flag, the driver can send a request, such as a request to reset a USB pipe (see WdfUsbTargetPipeResetSynchronously), to a device after the driver has called WdfIoTargetStop.

When a driver calls WdfIoTargetStop, the framework does not attempt to cancel or wait for I/O requests that were previously sent to the target using either the WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE flag or the WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET flag in the request's WDF_REQUEST_SEND_OPTIONS structure.

Your driver must call WdfIoTargetStart and WdfIoTargetStop synchronously. After the driver calls one of these functions, it must not call either function before the first call returns.

Your driver can call WdfIoTargetStop multiple times from a single thread without calling WdfIoTargetStart. For example, your driver might do the following:

Call WdfIoTargetStop and specify an Action value of WdfIoTargetLeaveSentIoPending.
Determine whether the target should resume processing I/O requests.
If the target should resume, call WdfIoTargetStart. Otherwise, call WdfIoTargetStop again with an Action value of WdfIoTargetCancelSentIo.

Note WdfIoTargetStop is not thread safe. It is not safe to call WdfIoTargetStop simultaneously from different threads.

For more information about I/O targets, see Using I/O Targets.

If the driver has called WdfUsbTargetPipeConfigContinuousReader for the pipe, WdfIoTargetStop must be called at IRQL = PASSIVE_LEVEL.

If the driver has not called WdfUsbTargetPipeConfigContinuousReader and if the Action parameter of WdfIoTargetStop is WdfIoTargetLeaveSentIoPending, WdfIoTargetStop can be called at IRQL <= DISPATCH_LEVEL. Otherwise, WdfIoTargetStop is called at IRQL = PASSIVE_LEVEL.

Examples

The following code example shows how an EvtDeviceD0Exit callback function can call WdfIoTargetStop, if the driver uses a continuous reader for a USB pipe.

NTSTATUS
MyEvtDeviceD0Exit(
    IN  WDFDEVICE Device,
    IN  WDF_POWER_DEVICE_STATE TargetState
)
{
    PDEVICE_CONTEXT  pDeviceContext;
    pDeviceContext = GetMyDeviceContext(Device);

    WdfIoTargetStop(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetCancelSentIo
                    );

    return STATUS_SUCCESS;
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfiotarget.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	See Remarks section.
DDI compliance rules	DriverCreate(kmdf), FailD0EntryIoTargetState(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Share via