Функция WdfIoQueuePurge (wdfio.h)

  • Статья

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

Метод WdfIoQueuePurge приводит к тому, что платформа прекращает очередь запросов ввода-вывода в очередь ввода-вывода и отменяет необработанные запросы.

Синтаксис

void WdfIoQueuePurge(
  [in]           WDFQUEUE               Queue,
  [in, optional] PFN_WDF_IO_QUEUE_STATE PurgeComplete,
  [in, optional] WDFCONTEXT             Context
);

Параметры

[in] Queue

Дескриптор объекта очереди платформы.

[in, optional] PurgeComplete

Указатель на функцию обратного вызова EvtIoQueueState , предоставляемую драйвером. Этот параметр является необязательным и может иметь значение NULL.

[in, optional] Context

Нетипизированный указатель на предоставленные драйвером сведения о контексте, которые платформа передает функции обратного вызова EvtIoQueueState . Этот параметр является необязательным и может иметь значение NULL.

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

None

Remarks

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

После вызова драйвером WdfIoQueuePurge платформа перестает добавлять запросы ввода-вывода в указанную очередь. Платформа отменяет все запросы, которые она не доставила на целевое устройство, и вызывает функцию обратного вызова CompletionRoutine драйвера для каждого из них. Платформа также пытается отменить (путем вызова IoCancelIrp) все запросы, доставленные на целевое устройство, которые не были помечены WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE.

Если платформа получает дополнительные запросы для очереди, она завершает их со значением состояния завершения STATUS_INVALID_DEVICE_STATE.

Если драйвер предоставляет функцию обратного вызова EvtIoQueueState , платформа вызывает ее после завершения или отмены всех запросов, которые были доставлены драйверу. Вы можете изменить irQL, по которому выполняется обратный вызов, указав ExecutionLevel в WDF_OBJECT_ATTRIBUTES во время создания очереди. Дополнительные сведения см. в разделе ПримечанияEVT_WDF_IO_QUEUE_STATE.

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

Если драйвер вызывает WdfRequestRequeue после вызова WdfIoQueuePurge, повторная попытка может завершиться до завершения очистки. В kmdf версии 1.9 и более ранних эта последовательность приводит к сбою операционной системы. Эта проблема устранена в KMDF версии 1.11 и более поздних.

Дополнительные сведения о методе WdfIoQueuePurge см. в разделе Управление очередями ввода-вывода.

Примеры

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

WdfIoQueuePurge(
                ReadQueue, 
                WDF_NO_EVENT_CALLBACK, 
                WDF_NO_CONTEXT 
                );

Требования

Требование Значение
Целевая платформа Универсальное
Минимальная версия KMDF 1,0
Минимальная версия UMDF 2,0
Верхняя часть wdfio.h (включая Wdf.h)
Библиотека Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL <= DISPATCH_LEVEL
Правила соответствия DDI ChangeQueueState(kmdf), DriverCreate(kmdf), EvtSurpriseRemoveNoSuspendQueue(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), NoCancelFromEvtSurpriseRemove(kmdf)

См. также раздел

EvtIoQueueState

WdfIoQueueDrain

WdfIoQueuePurgeSynchronously