Função WdfIoTargetFormatRequestForRead (wdfiotarget.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfIoTargetFormatRequestForRead cria uma solicitação de leitura para um destino de E/S, mas não envia a solicitação.

Sintaxe

NTSTATUS WdfIoTargetFormatRequestForRead(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         OutputBuffer,
  [in, optional] PWDFMEMORY_OFFSET OutputBufferOffset,
  [in, optional] PLONGLONG         DeviceOffset
);

Parâmetros

[in] IoTarget

Um identificador para um objeto de destino de E/S local ou remoto que foi obtido de uma chamada anterior para WdfDeviceGetIoTarget ou WdfIoTargetCreate, ou de um método que um destino de E/S especializado fornece.

[in] Request

Um identificador para um objeto de solicitação de estrutura. Para obter mais informações, consulte a seção Comentários a seguir.

[in, optional] OutputBuffer

Um identificador para um objeto de memória de estrutura. Esse objeto representa um buffer que receberá dados do destino de E/S. Esse parâmetro é opcional e pode ser NULL. Para obter mais informações sobre esse parâmetro, consulte a seção Comentários a seguir.

[in, optional] OutputBufferOffset

Um ponteiro para uma estrutura de WDFMEMORY_OFFSET alocada pelo chamador que fornece valores opcionais de deslocamento e comprimento de bytes. A estrutura usa esses valores para determinar o endereço inicial e o comprimento, dentro do buffer de saída, para a transferência de dados. Se esse ponteiro for NULL, a transferência de dados começará no início do buffer de saída e o tamanho da transferência será o tamanho do buffer.

[in, optional] DeviceOffset

Um ponteiro para uma variável que especifica um deslocamento inicial para a transferência. O destino de E/S (ou seja, o driver mais baixo) define como usar esse valor. Por exemplo, os drivers na pilha de driver de um disco podem especificar um deslocamento desde o início do disco. O destino de E/S obtém essas informações no membro Parameters.Read.DeviceOffset da estrutura WDF_REQUEST_PARAMETERS da solicitação. Esse ponteiro é opcional. A maioria dos drivers define esse ponteiro como NULL.

Retornar valor

WdfIoTargetFormatRequestForRead 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 inválido foi detectado.
STATUS_INVALID_DEVICE_REQUEST	O comprimento da transferência era maior que o comprimento do buffer ou a solicitação de E/S já estava na fila para um destino de E/S.
STATUS_INSUFFICIENT_RESOURCES	A estrutura não pôde alocar recursos do sistema (normalmente memória).
STATUS_REQUEST_NOT_ACCEPTED	O IRP (pacote de solicitação de E/S) que o parâmetro Request representa não fornece estruturas de IO_STACK_LOCATION suficientes para permitir que o driver encaminhe a solicitação.

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

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

Use o método WdfIoTargetFormatRequestForRead , seguido pelo método WdfRequestSend , para enviar solicitações de leitura de forma síncrona ou assíncrona. Como alternativa, use o método WdfIoTargetSendReadSynchronously para enviar solicitações de leitura de forma síncrona.

Você pode encaminhar uma solicitação de E/S recebida pelo driver em uma fila de E/S ou pode criar e enviar uma nova solicitação. Em ambos os casos, a estrutura requer um objeto de solicitação e algum espaço de buffer.

Para encaminhar uma solicitação de E/S que seu driver recebeu em uma fila de E/S:

Especifique o identificador da solicitação recebida para o parâmetro Request do método WdfIoTargetFormatRequestForRead.
Use o buffer de saída da solicitação recebida para o parâmetro OutputBuffer do método WdfIoTargetFormatRequestForRead.
O driver deve chamar WdfRequestRetrieveOutputMemory para obter um identificador para um objeto de memória de estrutura que representa o buffer de saída da solicitação e deve usar esse identificador como o valor de OutputBuffer.

Para obter mais informações sobre como encaminhar uma solicitação de E/S, consulte Encaminhando solicitações de E/S.

Os drivers geralmente dividem as solicitações de E/S recebidas em solicitações menores que eles enviam para um destino de E/S, para que o driver possa criar novas solicitações.

Para criar uma nova solicitação de E/S:

Crie um novo objeto de solicitação e forneça seu identificador para o parâmetro Request do método WdfIoTargetFormatRequestForRead.
Chame WdfRequestCreate para pré-alocar um ou mais objetos de solicitação. Você pode reutilizar esses objetos de solicitação chamando WdfRequestReuse. A função de retorno de chamada EvtDriverDeviceAdd do driver pode pré-alocar objetos de solicitação para um dispositivo.
Forneça espaço em buffer e forneça o identificador do buffer para o parâmetro OutputBuffer do método WdfIoTargetFormatRequestForRead.
Seu driver deve especificar esse espaço de buffer como um identificador WDFMEMORY para memória gerenciada por estrutura. O driver pode fazer um dos seguintes procedimentos:
- Chame WdfMemoryCreate ou WdfMemoryCreatePreallocated para criar um novo buffer de memória, se você quiser que o driver passe um novo buffer para o destino de E/S.
- Chame WdfRequestRetrieveOutputMemory para obter um identificador para o objeto de memória que representa o buffer de uma solicitação de E/S recebida, se você quiser que o driver passe o conteúdo desse buffer para o destino de E/S.
Observe que, se o driver chamar WdfRequestRetrieveOutputMemory e passar o identificador de memória para WdfIoTargetFormatRequestForRead, o driver não deverá concluir a solicitação de E/S recebida até que o driver exclua, reutilize ou reformate o novo objeto de solicitação criado pelo driver. (WdfIoTargetFormatRequestForRead incrementa a contagem de referência do objeto de memória. Excluir, reutilizar ou reformatar um objeto de solicitação diminui a contagem de referência do objeto de memória.)

Alguns destinos de E/S aceitam solicitações de leitura que têm um buffer de comprimento zero. Para esses destinos de E/S, seu driver pode especificar NULL para o parâmetro OutputBuffer .

Depois que um driver chama WdfIoTargetFormatRequestForRead para formatar uma solicitação de E/S, ele deve chamar WdfRequestSend para enviar a solicitação (de forma síncrona ou assíncrona) para um destino de E/S.

Várias chamadas para WdfIoTargetFormatRequestForRead que usam a mesma solicitação não causam alocações de recursos adicionais. Portanto, para reduzir a chance de WdfRequestCreate retornar STATUS_INSUFFICIENT_RESOURCES, a função de retorno de chamada EvtDriverDeviceAdd do driver pode chamar WdfRequestCreate para pré-alocar um ou mais objetos de solicitação para um dispositivo. O driver pode reutilizar posteriormente (chamar WdfRequestReuse), reformat (chamar WdfIoTargetFormatRequestForRead) e reenviar (chamar WdfRequestSend) cada objeto de solicitação sem arriscar um valor de retorno STATUS_INSUFFICIENT_RESOURCES de uma chamada posterior para WdfRequestCreate. Todas as chamadas subsequentes para WdfIoTargetFormatRequestForRead para o objeto de solicitação reutilizado retornarão STATUS_SUCCESS, se os valores de parâmetro não forem alterados. (Se o driver não chamar o mesmo método de formatação de solicitação todas as vezes, recursos adicionais poderão ser alocados.)

Para obter informações sobre como obter informações de status após a conclusão de uma solicitação de E/S, consulte Obtendo informações de conclusão.

Para obter mais informações sobre WdfIoTargetFormatRequestForRead, consulte Enviando solicitações de E/S para destinos gerais de E/S.

Para obter mais informações sobre destinos de E/S, consulte Usando destinos de E/S.

Exemplos

O exemplo de código a seguir cria um objeto de memória de estrutura para o buffer de saída de uma solicitação de leitura, formata a solicitação de leitura, registra uma função de retorno de chamada CompletionRoutine e envia a solicitação de leitura para um destino de E/S.

WDFREQUEST  request;
NTSTATUS  status;
WDFMEMORY  memory;
WDF_OBJECT_ATTRIBUTES  attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         DRIVER_TAG,
                         READ_BUF_SIZE,
                         &memory,
                         NULL
                         );

if (!NT_SUCCESS(status)) {
    return status;
}

status = WdfIoTargetFormatRequestForRead(
                                         IoTarget,
                                         request,
                                         memory,
                                         NULL,
                                         NULL
                                         );
if (!NT_SUCCESS(status)) {
        return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyReadRequestCompletionRoutine,
                               targetInfo
                               );
if (WdfRequestSend(
                   request,
                   IoTarget,
                   WDF_NO_SEND_OPTIONS
                   ) == FALSE) {
        status = WdfRequestGetStatus(request);
}

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	wdfiotarget.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf)