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

Статья
08/08/2023

[Применяется только к 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 добавляет запрос в очередь ввода-вывода для конкретного типа запроса драйвера для устройства, если драйвер создал его. В противном случае метод добавляет запрос в очередь устройства по умолчанию, если драйвер создал ее.

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

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

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

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

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

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

Для kmdf версий 1.0 и 1.5 необходимо вызывать 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 (включая 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

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