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

Статья
08/08/2023

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

Метод WdfRequestCreateFromIrp создает объект запроса платформы из указанного WDM IRP.

Синтаксис

NTSTATUS WdfRequestCreateFromIrp(
  [in, optional] PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in]           PIRP                   Irp,
  [in]           BOOLEAN                RequestFreesIrp,
  [out]          WDFREQUEST             *Request
);

Параметры

[in, optional] RequestAttributes

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

[in] Irp

Указатель на структуру IRP , содержащую пакет запроса ввода-вывода WDM.

[in] RequestFreesIrp

Логическое значение, которое, если значение TRUE, указывает, что платформа удаляет IRP при уничтожении дескриптора запроса. Если значение FALSE, драйвер должен вызвать IoFreeIrp , чтобы удалить IRP, выполнив действия, описанные в следующем разделе Примеры.

[out] Request

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

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

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

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

Как правило, драйверы на основе платформы вызывают WdfRequestCreateFromIrp только в том случае, если они получают WDM IRP в подпрограмме диспетчеризации WDM, а затем перенаправляют запросы в целевые объекты ввода-вывода платформы.

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

Кроме того, драйвер не должен вызывать WdfRequestRetrieveOutputMemory, WdfRequestRetrieveOutputBuffer, WdfRequestRetrieveInputBuffer или WdfRequestRetrieveInputMemory с новым объектом запроса.

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

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

Драйверы на основе платформы не должны использовать элемент Tail.Overlay.DriverContext структуры IRP , так как платформа использует этот элемент.

Примеры

Пример 1

В следующем примере кода создается объект запроса платформы из указанного WDM IRP, а затем удаляется. В этом примере параметру RequestFreesIrp присваиваетсязначение TRUE, поэтому платформа удаляет IRP при уничтожении дескриптора запроса.

WDFREQUEST request;
PIRP irp;

//Creation
status = WdfRequestCreateFromIrp(
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 irp,
                                 TRUE,
                                 &request
                                 );
...
//Deletion
WdfObjectDelete(request);

Пример 2

В следующем примере кода также создается объект запроса платформы из указанного WDM IRP, а затем удаляется. В этом примере параметру RequestFreesIrp присваиваетсязначение FALSE, поэтому драйвер должен вызвать IoFreeIrp , чтобы удалить IRP. Все вызовы функций в примере являются обязательными.

WDF_REQUEST_REUSE_PARAMS params;
WDFREQUEST request;
PIRP irp;

//Creation
status = WdfRequestCreateFromIrp(
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 irp,
                                 FALSE,
                                 &request
                                 );
...
//Deletion
WDF_REQUEST_REUSE_PARAMS_INIT(
                              &params,
                              WDF_REQUEST_REUSE_NO_FLAGS,
                              STATUS_SUCCESS
                              );
WDF_REQUEST_REUSE_PARAMS_SET_NEW_IRP(
                                     &params,
                                     NULL
                                     );
status = WdfRequestReuse(
                         request,
                         &params
                         );
ASSERT(NT_SUCCESS(status));
IoFreeIrp(irp);
WdfObjectDelete(request);

Требования

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