Функция WdfIoTargetStop (wdfiotarget.h)

Статья
08/08/2023

[Относится к KMDF и UMDF]

Метод WdfIoTargetStop прекращает отправку очередных запросов в локальный или удаленный целевой объект ввода-вывода.

Синтаксис

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

Параметры

[in] IoTarget

Дескриптор для локального или удаленного целевого объекта ввода-вывода, полученного при предыдущем вызове WdfDeviceGetIoTarget или WdfIoTargetCreate, или из метода, предоставленного специализированным целевым объектом ввода-вывода.

[in] Action

Значение типа WDF_IO_TARGET_SENT_IO_ACTION, указывающее, как платформа должна обрабатывать запросы ввода-вывода, отправленные драйвером в целевой объект ввода-вывода, если целевой объект не завершил запросы.

Возвращаемое значение

None

Remarks

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Если драйвер может обнаруживать ошибки устройства, которые можно восстановить, может потребоваться, чтобы драйвер вызвал WdfIoTargetStop , чтобы временно прекратить отправку запросов, а затем вызвать WdfIoTargetStart , чтобы возобновить отправку запросов.

Пока он остановлен, целевой объект ввода-вывода продолжает принимать новые запросы, но не доставляет запросы в очереди соответствующему драйверу.

Дополнительные сведения о возможных состояниях целевых объектов ввода-вывода см. в разделе Управление состоянием общего целевого объекта ввода-вывода.

Если драйвер вызывает WdfUsbTargetPipeConfigContinuousReader для настройки непрерывного средства чтения для USB-канала, функция обратного вызова EvtDeviceD0Exit драйвера должна вызвать WdfIoTargetStop , чтобы остановить средство чтения.

Если драйвер вызвал WdfIoTargetStop, он по-прежнему может отправить запрос целевому объекту, установив флаг WDF_REQUEST_OPTION_IGNORE_TARGET_STATE в структуре WDF_REQUEST_SEND_OPTIONS запроса. Если драйвер устанавливает этот флаг, драйвер может отправить запрос, например запрос на сброс USB-канала (см. раздел WdfUsbTargetPipeResetSynchronously) на устройство после вызова драйвера WdfIoTargetStop.

Когда драйвер вызывает WdfIoTargetStop, платформа не пытается отменить или ожидать запросов ввода-вывода, которые ранее были отправлены в целевой объект с помощью флага WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE или флага WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET в структуре WDF_REQUEST_SEND_OPTIONS запроса.

Драйвер должен вызывать WdfIoTargetStart и WdfIoTargetStop синхронно. После вызова одной из этих функций драйвер не должен вызывать ни одну из функций до возврата первого вызова.

Драйвер может вызывать WdfIoTargetStop несколько раз из одного потока, не вызывая WdfIoTargetStart. Например, драйвер может выполнять следующие действия:

Вызовите WdfIoTargetStop и укажите значение действияWdfIoTargetLeaveSentIoPending.
Определите, должен ли целевой объект возобновлять обработку запросов ввода-вывода.
Если целевой объект должен возобновиться, вызовите WdfIoTargetStart. В противном случае снова вызовите WdfIoTargetStop со значением ДействияWdfIoTargetCancelSentIo.

Примечание. WdfIoTargetStop не является потокобезопасной. WdfIoTargetStop небезопасно вызывать одновременно из разных потоков.

Дополнительные сведения о целевых объектах ввода-вывода см. в разделе Использование целевых объектов ввода-вывода.

Если драйвер вызвал WdfUsbTargetPipeConfigContinuousReader для канала, необходимо вызвать WdfIoTargetStop по адресу IRQL = PASSIVE_LEVEL.

Если драйвер не вызывал WdfUsbTargetPipeConfigContinuousReader и параметр ActionWdfIoTargetStop имеет значение WdfIoTargetLeaveSentIoPending, WdfIoTargetStop можно вызвать по адресу IRQL <= DISPATCH_LEVEL. В противном случае WdfIoTargetStop вызывается по адресу IRQL = PASSIVE_LEVEL.

Примеры

В следующем примере кода показано, как функция обратного вызова EvtDeviceD0Exit может вызывать WdfIoTargetStop, если драйвер использует непрерывное средство чтения для USB-канала.

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;
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfiotarget.h (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	См. раздел "Примечания".
Правила соответствия DDI	DriverCreate(kmdf), FailD0EntryIoTargetState(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)