Функция 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)