функция обратного вызова EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE (wdfio.h)
[Применимо к KMDF и UMDF]
Функция обратного вызова события EvtIoCanceledOnQueue драйвера сообщает драйверу, что он должен завершить запрос ввода-вывода, который платформа удалила из очереди ввода-вывода.
Синтаксис
EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE EvtWdfIoQueueIoCanceledOnQueue;
void EvtWdfIoQueueIoCanceledOnQueue(
[in] WDFQUEUE Queue,
[in] WDFREQUEST Request
)
{...}
Параметры
[in] Queue
Дескриптор объекта очереди ввода-вывода.
[in] Request
Дескриптор объекта запроса.
Возвращаемое значение
None
Remarks
Драйвер регистрирует функцию обратного вызова EvtIoCanceledOnQueue при вызове метода WdfIoQueueCreate . Дополнительные сведения о вызове WdfIoQueueCreate см. в разделе Создание очередей ввода-вывода.
Если драйвер регистрирует функцию обратного вызова EvtIoCanceledOnQueue для очереди ввода-вывода, платформа вызывает функцию обратного вызова в следующих ситуациях:
- Обработчик запросов получает запрос ввода-вывода из очереди ввода-вывода, драйвер вызывает WdfRequestForwardToIoQueue, WdfRequestForwardToParentDeviceIoQueue или WdfRequestRequeue, чтобы повторно отправить запрос в очередь ввода-вывода, для которой зарегистрирована функция обратного вызова EvtIoCanceledOnQueue, и связанная операция ввода-вывода впоследствии отменяется.
- Функция обратного вызова EvtIoInCallerContext драйвера получает запрос ввода-вывода, драйвер вызывает WdfDeviceEnqueueRequest для передачи запроса обратно в платформу, платформа помещает запрос в очередь ввода-вывода, для которой зарегистрирована функция обратного вызова EvtIoCanceledOnQueue , а связанная операция ввода-вывода впоследствии отменяется.
Как правило, в EvtIoCanceledOnQueue драйвер завершает запрос ввода-вывода с состоянием завершения STATUS_CANCELLED.
В некоторых случаях драйвер мог ранее отправить запрос ввода-вывода в очередь вручную, возможно, чтобы дождаться получения информации. Например, в одном из обработчиков запросов драйвер может поместить запрос ввода-вывода, связанный с ожидающей транзакцией DMA, в очередь вручную. В этом случае драйвер пытается отменить транзакцию DMA в обратном вызове EvtIoCanceledOnQueue . В зависимости от результатов операции отмены драйвер завершает запрос с соответствующим состоянием в EvtIoCanceledOnQueue или более поздней версии.
Платформа не вызывает функцию обратного вызова EvtIoCanceledOnQueue драйвера для запросов ввода-вывода, которые платформа никогда не доставляла драйверу.
Платформа вызывает функцию обратного вызова EvtIoCanceledOnQueue , как только определяет, что запрос ввода-вывода был отменен, независимо от метода диспетчеризации , заданного драйвером для очереди ввода-вывода. Поэтому платформа может вызывать функцию обратного вызова EvtIoCanceledOnQueue для:
- Запрос в очереди, использующий последовательную диспетчеризацию, даже если драйвер в настоящее время владеет другим запросом из очереди.
- Запрос в очереди, для которого драйвер задал NumberOfPresentedRequests, даже если драйвер в настоящее время владеет максимальным числом запросов.
Функция обратного вызова EvtIoCanceledOnQueue может вызываться по адресу IRQL <= DISPATCH_LEVEL, если для элемента ExecutionLevelWDF_OBJECT_ATTRIBUTES структуры устройства или драйвера не задано значение WdfExecutionLevelPassive.
Если IRQL PASSIVE_LEVEL, платформа вызывает функцию обратного вызова в критическом регионе.
Примеры
Чтобы определить функцию обратного вызова EvtIoCanceledOnQueue , необходимо сначала предоставить объявление функции, определяющее тип определяемой функции обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.
Чтобы определить функцию обратного вызова EvtIoCanceledOnQueue , необходимо сначала предоставить объявление функции, которое требуется SDV и другие средства проверки. Следующий пример взят из примера драйвера смарт-карты PCMCIA .
EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE PscrEvtIoCanceledOnQueue;
В примере драйвера смарт-карты PCMCIA драйвер использует очередь вручную для хранения ожидающих запросов уведомлений смарт-карта. Драйвер предоставляет функцию обратного вызова EvtIoCanceledOnQueue , в которой драйвер очищает поле уведомления и завершает запрос.
_Use_decl_annotations_
VOID
PscrEvtIoCanceledOnQueue(
WDFQUEUE Queue,
WDFREQUEST Request
)
{
PDEVICE_EXTENSION DeviceExtension;
PSMARTCARD_EXTENSION smartcardExtension;
DeviceExtension = GetDeviceExtension(WdfIoQueueGetDevice(Queue));
smartcardExtension = (PSMARTCARD_EXTENSION) &DeviceExtension->SmartcardExtension;
//KdPrint(("Cancelled on queue 0x%x\n", WdfRequestWdmGetIrp(Request)));
InterlockedExchangePointer(
&(smartcardExtension->OsData->NotificationIrp),
NULL
);
WdfRequestComplete(Request, STATUS_CANCELLED);
}
Тип функции EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE определяется в файле заголовка Wdfio.h. Чтобы более точно определить ошибки при запуске средств анализа кода, обязательно добавьте заметку Use_decl_annotations в определение функции. Заметка Use_decl_annotations гарантирует использование заметок, которые применяются к типу функции EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в разделе Объявление функций с помощью типов ролей функций для драйверов KMDF. Сведения о Use_decl_annotations см. в статье О поведении функции.
Требования
| Требование | Значение |
|---|---|
| Целевая платформа | Универсальное |
| Минимальная версия KMDF | 1,0 |
| Минимальная версия UMDF | 2,0 |
| Верхняя часть | wdfio.h (включая Wdf.h) |
| IRQL | <= DISPATCH_LEVEL (см. раздел "Примечания") |