Função WdfRequestRetrieveOutputMemory (wdfrequest.h)

[Aplica-se a KMDF e UMDF]

O método WdfRequestRetrieveOutputMemory recupera um identificador para um objeto de memória de estrutura que representa o buffer de saída de uma solicitação de E/S.

Sintaxe

NTSTATUS WdfRequestRetrieveOutputMemory(
  [in]  WDFREQUEST Request,
  [out] WDFMEMORY  *Memory
);

Parâmetros

[in] Request

Um identificador para um objeto de solicitação de estrutura.

[out] Memory

Um ponteiro para um local que recebe um identificador para um objeto de memória de estrutura.

Retornar valor

WdfRequestRetrieveOutputMemory 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_INVALID_DEVICE_REQUEST
O tipo de solicitação não é válido ou a solicitação não está usando e/S direta nem buffer. Para obter mais informações sobre métodos com suporte para acessar buffers de dados, consulte a seção Comentários a seguir.
STATUS_INTERNAL_ERROR
A solicitação já foi concluída.
STATUS_BUFFER_TOO_SMALL
O comprimento do buffer de saída é zero.
STATUS_INSUFFICIENT_RESOURCES
Não há memória suficiente.
 

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

O buffer de saída de uma solicitação recebe informações, como dados de um disco, que o driver fornece ao originador da solicitação. Seu driver pode chamar WdfRequestRetrieveOutputMemory para obter o buffer de saída para uma solicitação de leitura ou uma solicitação de controle de E/S do dispositivo, mas não para uma solicitação de gravação (porque as solicitações de gravação não fornecem dados de saída).

O método WdfRequestRetrieveOutputMemory recupera o buffer de saída para solicitações de E/S que usam o método de E/S armazenado em buffer ou o método de E/S direto para acessar buffers de dados. Se o código de controle de E/S da solicitação for IRP_MJ_INTERNAL_DEVICE_CONTROL ou se a solicitação veio de outro driver no modo kernel, WdfRequestRetrieveOutputMemory também oferecerá suporte a solicitações de E/S que não usam E/S nem buffer.

Se WdfRequestRetrieveOutputMemory retornar STATUS_SUCCESS, o driver receberá um identificador para um objeto de memória de estrutura que representa o buffer de saída. Para acessar o buffer, o driver deve chamar WdfMemoryGetBuffer.

O driver pode acessar o objeto de memória da estrutura recuperada até concluir a solicitação de E/S que o parâmetro Request representa.

Em vez de chamar WdfRequestRetrieveOutputMemory, o driver pode chamar WdfRequestRetrieveOutputBuffer, que recupera o endereço e o comprimento do buffer.

Para obter mais informações sobre WdfRequestRetrieveOutputMemory, consulte Acessando buffers de dados em drivers de Framework-Based.

Exemplos

O exemplo de código a seguir mostra como uma função de retorno de chamada EvtIoRead pode obter um identificador para o objeto de memória da estrutura que representa o buffer de saída de uma solicitação de leitura. Em seguida, o exemplo formata e envia a solicitação de leitura para um destino de E/S USB.

VOID 
MyEvtIoRead(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    WDFUSBPIPE  pipe;
    NTSTATUS  status;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;

    //
    // The driver previously stored a pipe handle in 
    // the device object's context space.
    //
    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
    pipe = pDeviceContext->BulkReadPipe;

    //
    // Get output memory.
    //
    status = WdfRequestRetrieveOutputMemory(
                                            Request,
                                            &reqMemory
                                            );
    if(!NT_SUCCESS(status)){
        goto Exit;
    }
    //
    // Format the request.
    //
    status = WdfUsbTargetPipeFormatRequestForRead(
                                           pipe,
                                           Request,
                                           reqMemory,
                                           NULL
                                           ); 
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestReadCompletionRoutine,
                                   pipe
                                   );
    //
    // Send the request.
    //
    if (WdfRequestSend(
                       Request,
                       WdfUsbTargetPipeGetIoTarget(pipe),
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
        goto Exit;
    }
Exit:
    //
    // Complete the request now if an error occurred.
    //
    if (!NT_SUCCESS(status)) {
        WdfRequestCompleteWithInformation(
                                          Request,
                                          status,
                                          0
                                          );
    }
    return;
}

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), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MemAfterReqCompletedIntIoctl(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctl(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedRead(kmdf), MemAfterReqCompletedReadA(kmdf), MemAfterReqCompletedWrite(kmdf), OutputBufferAPI(kmdf)

Confira também

WdfMemoryGetBuffer

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputBuffer