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

Статья
08/08/2023

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

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

Синтаксис

void WdfIoTargetPurge(
  [in] WDFIOTARGET                   IoTarget,
  [in] WDF_IO_TARGET_PURGE_IO_ACTION Action
);

Параметры

[in] IoTarget

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

[in] Action

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

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

None

Remarks

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

Если драйвер ранее вызывал WdfUsbTargetPipeConfigContinuousReader, необходимо вызвать WdfIoTargetPurge по адресу IRQL = PASSIVE_LEVEL. Если драйвер не вызывал WdfUsbTargetPipeConfigContinuousReader и параметр ActionWdfIoTargetPurge имеет значение WdfIoTargetPurgeIo, WdfIoTargetPurge можно вызвать по адресу IRQL <= DISPATCH_LEVEL. В противном случае WdfIoTargetPurge необходимо вызвать по адресу IRQL = PASSIVE_LEVEL.

Чтобы сделать WdfIoTargetPurge синхронным вызовом, драйвер может задать значение WdfIoTargetPurgeIoAndWait параметра Action . В этом случае WdfIoTargetPurge ожидает возврата, пока все доставленные запросы не будут завершены или отменены.

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

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

После очистки очереди ввода-вывода драйвер может перезапустить очередь, вызвав WdfIoTargetStart.

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

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

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

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

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

Примеры

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

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

    WdfIoTargetPurge(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetPurgeIoAndWait
                    );

    return STATUS_SUCCESS;
}

Требования

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