Função WdfRequestCreateFromIrp (wdfrequest.h)

Artigo
03/01/2024

[Aplica-se somente ao KMDF]

O método WdfRequestCreateFromIrp cria um objeto de solicitação de estrutura de um WDM IRP especificado.

Sintaxe

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

Parâmetros

[in, optional] RequestAttributes

Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES alocada pelo chamador que especifica atributos de objeto para o objeto de solicitação. Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[in] Irp

Um ponteiro para uma estrutura IRP que contém um pacote de solicitação de E/S do WDM.

[in] RequestFreesIrp

Um valor booliano que, se TRUE, indica que a estrutura remove o IRP quando o identificador de solicitação é destruído. Se FALSE, o driver deverá chamar IoFreeIrp para remover o IRP, usando as etapas demonstradas pela seção Exemplos a seguir.

[out] Request

Um ponteiro para um local que recebe um identificador para um objeto de solicitação de estrutura.

Retornar valor

WdfRequestCreateFromIrp retornará STATUS_SUCCESS se a operação for bem-sucedida. Para obter uma lista de valores retornados adicionais, consulte Erros de criação de objeto da estrutura.

Esse método também pode retornar outros valores NTSTATUS.

Comentários

Normalmente, os drivers baseados em estrutura chamam WdfRequestCreateFromIrp somente se receberem IRPs do WDM em uma rotina de expedição do WDM e encaminharem as solicitações para destinos de E/S da estrutura.

Se um driver chamar WdfRequestCreateFromIrp para criar um objeto de solicitação, ele não deverá chamar WdfRequestComplete para o objeto de solicitação. Em vez disso, o driver deve chamar WdfObjectDelete quando terminar de usar o objeto de solicitação.

Além disso, o driver não deve chamar WdfRequestRetrieveOutputMemory, WdfRequestRetrieveOutputBuffer, WdfRequestRetrieveInputBuffer ou WdfRequestRetrieveInputMemory com o novo objeto de solicitação.

Por padrão, o pai do novo objeto de solicitação é o objeto de driver de estrutura que o método WdfDriverCreate criou. Você pode usar o membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES para especificar um pai diferente. A estrutura exclui o objeto de solicitação quando exclui o objeto pai. Se o driver não alterar o pai padrão, o driver deverá excluir o objeto de solicitação quando terminar de usar o objeto ; caso contrário, o objeto de solicitação permanecerá até que o gerente de E/S descarregue seu driver.

Para obter mais informações sobre como criar objetos de solicitação de estrutura, consulte Criando objetos de solicitação de estrutura.

Os drivers baseados em estrutura não devem usar o membro Tail.Overlay.DriverContext da estrutura IRP , pois a estrutura usa esse membro.

Exemplos

Exemplo 1

O exemplo de código a seguir cria um objeto de solicitação de estrutura de um WDM IRP especificado e o exclui. Este exemplo define o parâmetro RequestFreesIrp como TRUE, portanto, a estrutura remove o IRP quando o identificador de solicitação é destruído.

WDFREQUEST request;
PIRP irp;

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

Exemplo 2

O exemplo de código a seguir também cria um objeto de solicitação de estrutura de um WDM IRP especificado e o exclui. Este exemplo define o parâmetro RequestFreesIrp como FALSE, portanto, o driver deve chamar IoFreeIrp para remover o IRP. Todas as chamadas de função no exemplo são necessárias.

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

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Cabeçalho	wdfrequest.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.)
IRQL	<=DISPATCH_LEVEL
Regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)