Функция WdfRequestCreate (wdfrequest.h)

Статья
08/08/2023

[Применимо к KMDF и UMDF]

Метод WdfRequestCreate создает пустой объект запроса платформы.

Синтаксис

NTSTATUS WdfRequestCreate(
  [in, optional] PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in, optional] WDFIOTARGET            IoTarget,
  [out]          WDFREQUEST             *Request
);

Параметры

[in, optional] RequestAttributes

Указатель на структуру, выделенную вызывающим объектом WDF_OBJECT_ATTRIBUTES , которая задает атрибуты объекта для объекта запроса. Этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES.

[in, optional] IoTarget

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

[out] Request

Указатель на расположение, которое получает дескриптор объекта запроса платформы.

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

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

Код возврата	Описание
STATUS_INVALID_PARAMETER	Недопустимый входной параметр.
STATUS_INSUFFICIENT_RESOURCES	Для завершения операции недостаточно системных ресурсов.
STATUS_REQUEST_NOT_ACCEPTED	Массив расположений стека ввода-вывода запроса недостаточно велик, чтобы позволить драйверу отправить запрос в указанный целевой объект ввода-вывода.

Список дополнительных возвращаемых значений см. в разделе Ошибки создания объектов платформы.

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

Драйвер на основе платформы может вызвать WdfRequestCreate , чтобы создать новый запрос, который драйвер впоследствии передает другим функциям платформы для инициализации. Например, драйвер для USB-устройства может вызвать WdfUsbTargetPipeFormatRequestForRead для форматирования нового запроса на чтение.

Драйвер на основе платформы, взаимодействующий с драйверами WDM, может указать содержимое запроса, вызвав WdfRequestCreateFromIrp.

Если драйвер вызывает WdfRequestCreate для создания объекта запроса, он не должен вызывать WdfRequestComplete для объекта запроса. Вместо этого драйвер должен вызвать WdfObjectDelete после завершения работы с объектом запроса. Дополнительные сведения см. в разделе Завершение запросов ввода-вывода.

По умолчанию родительским объектом нового объекта запроса является объект драйвера платформы, созданный методом WdfDriverCreate . Для указания другого родительского элемента можно использовать элемент ParentObjectструктуры WDF_OBJECT_ATTRIBUTES . Платформа удаляет объект запроса при удалении родительского объекта. Если драйвер не изменяет родительский объект по умолчанию, драйвер должен удалить объект запроса после завершения работы с объектом . В противном случае объект запроса останется до тех пор, пока диспетчер ввода-вывода не выгрузит драйвер.

Дополнительные сведения о вызове WdfRequestCreate см. в разделе Создание объектов запроса платформы.

Примеры

В следующем примере кода создается целевой объект ввода-вывода, инициализируется структура WDF_OBJECT_ATTRIBUTES и вызывается WdfRequestCreate. Родительским объектом нового объекта запроса является целевой объект ввода-вывода.

WDF_OBJECT_ATTRIBUTES  attributes;
WDFREQUEST newRequest;
WDFIOTARGET ioTarget;
...
status = WdfIoTargetCreate(
                           Device,
                           WDF_NO_OBJECT_ATTRIBUTES,
                           &ioTarget
                           );
  ...
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = ioTarget;

status = WdfRequestCreate(
                          &attributes,
                          ioTarget,
                          &newRequest
                          );

if (!NT_SUCCESS(status)) {
    return status;
}

Требования

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