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

Статья
08/08/2023

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

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

Синтаксис

NTSTATUS WdfIoQueueReadyNotify(
  [in]           WDFQUEUE               Queue,
  [in, optional] PFN_WDF_IO_QUEUE_STATE QueueReady,
  [in, optional] WDFCONTEXT             Context
);

Параметры

[in] Queue

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

[in, optional] QueueReady

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

[in, optional] Context

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

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

WdfIoQueueReadyNotify возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может вернуть одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_PARAMETER	Драйвер предоставил недопустимый дескриптор.
STATUS_INVALID_DEVICE_REQUEST	Это значение возвращается, если происходит одно из следующих действий: Элемент DispatchType структуры WDF_IO_QUEUE_CONFIG указанной очереди ввода-вывода не является WdfIoQueueDispatchManual. Драйвер ранее вызывал WdfIoQueueReadyNotify и зарегистрировал функцию обратного вызова EvtIoQueueState . Драйвер пытается отменить регистрацию функции обратного вызова уведомлений, но функция обратного вызова не зарегистрирована или драйвер не вызвал WdfIoQueueStop или WdfIoQueueStopSynchronously.

Код возврата

Описание

STATUS_INVALID_PARAMETER

Драйвер предоставил недопустимый дескриптор.

STATUS_INVALID_DEVICE_REQUEST

Это значение возвращается, если происходит одно из следующих действий:

Элемент DispatchType структуры WDF_IO_QUEUE_CONFIG указанной очереди ввода-вывода не является WdfIoQueueDispatchManual.
Драйвер ранее вызывал WdfIoQueueReadyNotify и зарегистрировал функцию обратного вызова EvtIoQueueState .
Драйвер пытается отменить регистрацию функции обратного вызова уведомлений, но функция обратного вызова не зарегистрирована или драйвер не вызвал WdfIoQueueStop или WdfIoQueueStopSynchronously.

Этот метод также может возвращать другие значения NTSTATUS.

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

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

Платформа не вызывает EvtIoQueueState во время остановки указанной очереди. При запуске очереди платформа вызывает EvtIoQueueState , если очередь не пуста.

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

Функция обратного вызова EvtIoQueueState обычно вызывает WdfIoQueueRetrieveNextRequest или WdfIoQueueRetrieveRequestByFileObject в цикле, чтобы получить все запросы, полученные с момента последнего выполнения функции обратного вызова.

Чтобы платформа не вызывала функцию обратного вызова EvtIoQueueState , драйвер должен снова вызвать WdfIoQueueReadyNotify с параметром QueueReady , имеющим значение NULL. Однако драйвер должен сначала вызвать WdfIoQueueStop или WdfIoQueueStopSynchronously , чтобы остановить очередь ввода-вывода. Впоследствии драйвер может вызвать WdfIoQueueStart , чтобы перезапустить очередь.

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

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

Примеры

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

Status = WdfIoQueueReadyNotify(
                               ReadQueue,
                               EvtIoQueueReady,
                               myQueueContext
                               );

Требования

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

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

EvtIoQueueState

WDF_IO_QUEUE_CONFIG

WdfIoQueueRetrieveNextRequest

WdfIoQueueRetrieveRequestByFileObject