Função WdfRequestCreate (wdfrequest.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfRequestCreate cria um objeto de solicitação de estrutura vazio.

Sintaxe

NTSTATUS WdfRequestCreate(
  [in, optional] PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in, optional] WDFIOTARGET            IoTarget,
  [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, optional] IoTarget

Um identificador para um objeto de destino de E/S de estrutura. Esse parâmetro é opcional e pode ser NULL. Se não for NULL, WdfRequestCreate verificará se o driver pode eventualmente enviar a solicitação para o destino de E/S especificado.

[out] Request

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

Retornar valor

WdfRequestCreate retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método poderá retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um parâmetro de entrada é inválido.
STATUS_INSUFFICIENT_RESOURCES	Não há recursos suficientes do sistema para concluir a operação.
STATUS_REQUEST_NOT_ACCEPTED	A matriz de locais de pilha de E/S da solicitação não é grande o suficiente para permitir que o driver envie a solicitação para o destino de E/S especificado.

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

Um driver baseado em estrutura pode chamar WdfRequestCreate para criar uma nova solicitação que o driver passa posteriormente para outras funções de estrutura para inicialização. Por exemplo, um driver para um dispositivo USB pode chamar WdfUsbTargetPipeFormatRequestForRead para formatar uma nova solicitação de leitura.

Um driver baseado em estrutura que se comunica com drivers WDM pode especificar o conteúdo de uma solicitação chamando WdfRequestCreateFromIrp.

Se um driver chamar WdfRequestCreate 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. Para obter mais informações, consulte Concluindo solicitações de E/S.

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 chamar WdfRequestCreate, consulte Criando objetos de solicitação de estrutura.

Exemplos

O exemplo de código a seguir cria um objeto de destino de E/S, inicializa uma estrutura WDF_OBJECT_ATTRIBUTES e chama WdfRequestCreate. O pai do novo objeto de solicitação é o 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
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2,0
Cabeçalho	wdfrequest.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regras de conformidade de DDI	DriverCreate(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReqDelete(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting2(kmdf)