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 puede ser WDF_NO_OBJECT_ATTRIBUTES.

[in, optional] IoTarget

Identificador de un objeto de destino de E/S de marco. Este parámetro es opcional y puede ser NULL. Si no es NULL, 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 podría devolver otros valores NTSTATUS.

Comentarios

Un controlador basado en marcos puede llamar a WdfRequestCreate para crear una nueva solicitud que el controlador pasa posteriormente a otras funciones de 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 mediante una llamada 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 método WdfDriverCreate . Puede usar el miembro ParentObject de la estructura WDF_OBJECT_ATTRIBUTES para especificar otro elemento primario. 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	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfrequest.h (incluir Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReqDelete(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting2(kmdf)