Функция WdfDeviceEnqueueRequest (wdfdevice.h)

Статья
02/07/2025

[Применимо только к KMDF]

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

Синтаксис

NTSTATUS WdfDeviceEnqueueRequest(
  [in] WDFDEVICE  Device,
  [in] WDFREQUEST Request
);

Параметры

[in] Device

Дескриптор объекта устройства платформы.

[in] Request

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

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

Если операция выполнена успешно, метод возвращает STATUS_SUCCESS. К дополнительным возвращаемым значениям относятся:

Возвращаемый код	Описание
STATUS_INSUFFICIENT_RESOURCES	Объем доступной памяти низкий.
STATUS_INVALID_DEVICE_REQUEST	Драйвер не создал очереди ввода-вывода для устройства, а драйвер не является драйвером фильтра.
STATUS_WDF_BUSY	Очередь ввода-вывода устройства не принимает запросы.

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

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

Замечания

Драйвер может вызывать WdfDeviceEnqueueRequest только из функции обратного вызова EvtIoInCallerCon text.

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

Если драйвер не создал очереди ввода-вывода для устройства, WdfDeviceEnqueueRequest выполните следующие действия:

Если драйвер является драйвером фильтра, WdfDeviceEnqueueRequest отправляет запрос на целевой объект ввода-вывода драйвера.
Если драйвер не является драйвером фильтра, WdfDeviceEnqueueRequest возвращает STATUS_INVALID_DEVICE_REQUEST.

Хотя выполняется WdfDeviceEnqueueRequest, драйвер может получить и завершить или отменить запрос.

В результате, если драйверу необходимо использовать запрос или его контекст после вызова WdfDeviceEnqueueRequest, перед вызовом WdfDeviceEnqueueRequest.

Для этого драйвер может вызывать WdfObjectReference до, а затем WdfObjectDereference после вызова WdfDeviceEnqueueRequest. Драйвер должен разыменовывание запроса перед выходом EvtIoInCallerContext.

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

Для версий 1.0 и 1.5 KMDF WdfDeviceEnqueueRequest необходимо вызывать в PASSIVE_LEVEL. Для версий 1.7 и более поздних версий WdfDeviceEnqueueRequest можно вызвать в IRQL <= DISPATCH_LEVEL.

Примеры

Следующий пример кода — это функция обратного вызова EvtIoInCallerContext, которая ищет запросы, содержащие пользовательский код элемента управления ввода-вывода, IOCTL_NONPNP_METHOD_NEITHER. Если код элемента управления ввода-вывода не найден, функция обратного вызова просто возвращает запрос в платформу. Если функция обратного вызова находит код элемента управления ввода-вывода, он предварительно обрабатывает запрос, а затем возвращает его в платформу. Если возникла ошибка, функция обратного вызова завершает запрос.

VOID
MyEvtDeviceIoInCallerContext(
    IN WDFDEVICE  Device,
    IN WDFREQUEST Request
    )
{
    NTSTATUS  status = STATUS_SUCCESS;
    WDF_REQUEST_PARAMETERS  params;

    WDF_REQUEST_PARAMETERS_INIT(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );
    if(!(params.Type == WdfRequestTypeDeviceControl &&
         params.Parameters.DeviceIoControl.IoControlCode == IOCTL_NONPNP_METHOD_NEITHER)) {
        status = WdfDeviceEnqueueRequest(
                                         Device,
                                         Request
                                         );
        if(!NT_SUCCESS(status)) {
            goto End;
        }
        return;
    }
    //
    // Found a match for the control code. Preprocess the request, and then
    // return the request to the framework.
    //

    //...(Preprocess the request here.)

    status = WdfDeviceEnqueueRequest(
                                     Device,
                                     Request
                                     );
    if(!NT_SUCCESS(status)) {
        goto End;
    }
    return;
End:
    WdfRequestComplete(
                       Request,
                       status
                       );
    return;
}

Требования

Требование	Ценность
целевая платформа	Всеобщий
минимальная версия KMDF	1.0
заголовка	wdfdevice.h (include Wdf.h)
библиотеки	Wdf01000.sys (см. управление версиями библиотеки Платформы).)
IRQL	<= DISPATCH_LEVEL (см. раздел примечаний)
правил соответствия DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), kmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)

См. также

WDF_REQUEST_PARAMETERS_INIT

WdfRequestComplete

WdfRequestGetParameters

Поделиться через