Função WdfRequestRetrieveOutputBuffer (wdfrequest.h)

[Aplica-se a KMDF e UMDF]

O método WdfRequestRetrieveOutputBuffer recupera o buffer de saída de uma solicitação de E/S.

Sintaxe

NTSTATUS WdfRequestRetrieveOutputBuffer(
  [in]            WDFREQUEST Request,
  [in]            size_t     MinimumRequiredSize,
  [out]           PVOID      *Buffer,
  [out, optional] size_t     *Length
);

Parâmetros

[in] Request

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

[in] MinimumRequiredSize

O tamanho mínimo do buffer, em bytes, que o driver precisa para processar a solicitação de E/S.

[out] Buffer

Um ponteiro para um local que recebe o endereço do buffer.

[out, optional] Length

Um ponteiro para um local que recebe o tamanho do buffer, em bytes. Esse parâmetro é opcional e pode ser NULL.

Retornar valor

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

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 WdfRequestRetrieveOutputBuffer 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 WdfRequestRetrieveOutputBuffer 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, WdfRequestRetrieveOutputBuffer também oferecerá suporte a solicitações de E/S que não usam E /S nem buffer.

Se WdfRequestRetrieveOutputBuffer retornar STATUS_SUCCESS, o driver receberá o endereço e, opcionalmente, o tamanho do buffer de saída.

O driver pode acessar o buffer recuperado até concluir a solicitação de E/S que o parâmetro Request representa.

Em vez de chamar WdfRequestRetrieveOutputBuffer, o driver pode chamar WdfRequestRetrieveOutputMemory, que cria um objeto de memória de estrutura que representa o buffer.

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

Exemplos

O exemplo de código a seguir faz parte de uma função de retorno de chamada EvtIoDeviceControl . Este exemplo obtém o descritor de configuração de um dispositivo USB e coloca o descritor no buffer de saída da solicitação de E/S.

VOID
MyEvtIoDeviceControl(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  OutputBufferLength,
    IN size_t  InputBufferLength,
    IN ULONG  IoControlCode    
    )
{
    WDFDEVICE  device;
    PDEVICE_CONTEXT  pDevContext;
    size_t  bytesReturned = 0;
    NTSTATUS  status;

    device = WdfIoQueueGetDevice(Queue);
    //
    // GetDeviceContext is a driver-defined function 
    // to retrieve device object context space.
    //
    pDevContext = GetDeviceContext(device);

    switch(IoControlCode) {

      case IOCTL_OSRUSBFX2_GET_CONFIG_DESCRIPTOR: {
 
        PUSB_CONFIGURATION_DESCRIPTOR  configurationDescriptor = NULL;
        USHORT  requiredSize;

        //
        // First, get the size of the USB configuration descriptor.
        //
        status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                                pDevContext->UsbDevice,
                                                NULL,
                                                &requiredSize
                                                );
        if (status == STATUS_BUFFER_TOO_SMALL) {
            break;
        }

        //
        // Get the buffer. Make sure the buffer is big
        // enough to hold the configuration descriptor.
        //
        status = WdfRequestRetrieveOutputBuffer(
                                                Request, 
                                                (size_t)requiredSize,
                                                &configurationDescriptor,
                                                NULL
                                                );
        if(!NT_SUCCESS(status)){
            break;
        }
        //
        // Now get the config descriptor.
        //
        status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                                pDevContext->UsbDevice,
                                                configurationDescriptor,
                                                &requiredSize
                                                );
        if (!NT_SUCCESS(status)) {
            break;
        }

        bytesReturned = requiredSize;
      }
        break;
...
    (Other case statements removed.)
...
    default:
        status = STATUS_INVALID_DEVICE_REQUEST;
        break;
    }
    //
    // Complete the request.
    //
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      bytesReturned
                                      );
    return;
}

Requisitos

Confira também

WdfRequestRetrieveInputBuffer

WdfRequestRetrieveOutputMemory