Función WdfRequestCreate (wdfrequest.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

El método WdfRequestCreate crea un objeto de solicitud de marco vacío.

Sintaxis

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

Parámetros

[in, optional] RequestAttributes

Puntero a una estructura de WDF_OBJECT_ATTRIBUTES asignada por el autor de la llamada que especifica los atributos de objeto para el objeto de solicitud. Este parámetro es opcional y se puede WDF_NO_OBJECT_ATTRIBUTES.

[in, optional] IoTarget

Identificador de un objeto de destino de E/S de marco. Este parámetro es opcional y se puede NULL. Si noNULL, WdfRequestCreate comprueba que el controlador puede enviar finalmente la solicitud al destino de E/S especificado.

[out] Request

Puntero a una ubicación que recibe un identificador de un objeto de solicitud de marco.

Valor devuelto

WdfRequestCreate devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Un parámetro de entrada no es válido.
STATUS_INSUFFICIENT_RESOURCES	No hay recursos del sistema suficientes para completar la operación.
STATUS_REQUEST_NOT_ACCEPTED	La matriz de ubicaciones de pila de E/S de la solicitud no es lo suficientemente grande como para permitir que el controlador envíe la solicitud al destino de E/S especificado.

Para obtener una lista de valores devueltos adicionales, vea Errores de creación de objetos de marco.

Este método también puede devolver otros valores de NTSTATUS.

Observaciones

Un controlador basado en marcos puede llamar a WdfRequestCreate para crear una nueva solicitud que el controlador pasa posteriormente a otras funciones del marco para la inicialización. Por ejemplo, un controlador para un dispositivo USB podría llamar a WdfUsbTargetPipeFormatRequestForRead para dar formato a una nueva solicitud de lectura.

Un controlador basado en marco que se comunica con controladores WDM puede especificar el contenido de una solicitud llamando a WdfRequestCreateFromIrp.

Si un controlador llama a WdfRequestCreate para crear un objeto de solicitud, no debe llamar a WdfRequestComplete para el objeto de solicitud. En su lugar, el controlador debe llamar a WdfObjectDelete cuando haya terminado de usar el objeto de solicitud. Para obtener más información, consulte Finalización de solicitudes de E/S.

De forma predeterminada, el nuevo objeto primario del objeto de solicitud es el objeto de controlador de marco que creó el WdfDriverCreate método. Puede usar el miembro parentObject de de la estructura WDF_OBJECT_ATTRIBUTES para especificar un elemento primario diferente. El marco elimina el objeto de solicitud cuando elimina el objeto primario. Si el controlador no cambia el elemento primario predeterminado, el controlador debe eliminar el objeto de solicitud cuando haya terminado de usar el objeto ; De lo contrario, el objeto de solicitud permanecerá hasta que el administrador de E/S descargue el controlador.

Para obtener más información sobre cómo llamar a WdfRequestCreate, vea Creating Framework Request Objects.

Ejemplos

En el ejemplo de código siguiente se crea un objeto de destino de E/S, se inicializa una estructura de WDF_OBJECT_ATTRIBUTES y se llama a WdfRequestCreate. El nuevo objeto primario del objeto de solicitud es el objeto de destino de E/S.

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;
}

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
versión mínima de KMDF	1.0
versión mínima de UMDF	2.0
encabezado de	wdfrequest.h (incluya Wdf.h)
biblioteca de	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
irQL	<=DISPATCH_LEVEL
reglas de cumplimiento de DDI	DriverCreate(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfdfIrqlExplicit(kmdf), ReqDelete(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting2(kmdf)