Método IWDFIoRequest2::RetrieveOutputBuffer (wudfddi.h)

Artigo
08/08/2023

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum novo recurso está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Os drivers universais do Windows devem usar o UMDF 2. Para obter mais informações, consulte Introdução com UMDF.]

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

Sintaxe

HRESULT RetrieveOutputBuffer(
  [in]            SIZE_T MinimumRequiredCb,
  [out]           PVOID  *Buffer,
  [out, optional] SIZE_T *BufferCb
);

Parâmetros

[in] MinimumRequiredCb

O tamanho mínimo do buffer, em bytes, que o driver precisa para processar a solicitação de E/S. Esse valor poderá ser zero se não houver tamanho mínimo do buffer.

[out] Buffer

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

[out, optional] BufferCb

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

Retornar valor

RequestRetrieveOutputBuffer retorna S_OK se a operação for bem-sucedida. Caso contrário, esse método pode retornar o seguinte valor:

Código de retorno	Descrição
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	A solicitação de E/S não forneceu um buffer de saída ou o tamanho do buffer de saída é menor do que o tamanho mínimo especificado por MinimumRequiredCb .
E_OUTOFMEMORY	Não há memória suficiente disponível para recuperar o buffer. O driver deve concluir a solicitação com um erro status valor.

Esse método pode retornar um dos outros valores que Winerror.h contém.

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 RequestRetrieveOutputBuffer 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 RequestRetrieveOutputBuffer recupera o buffer de saída para solicitações de E/S que usam o método de E/S em buffer ou E /S direto para acessar buffers de dados.

Se RequestRetrieveOutputBuffer retornar S_OK, 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.

Em vez de chamar RequestRetrieveOutputBuffer, o driver pode chamar IWDFIoRequest2::RetrieveOutputMemory, que cria um objeto de memória de estrutura que representa o buffer.

Para obter mais informações sobre como acessar os buffers de dados de uma solicitação de E/S, consulte Acessando buffers de dados em drivers de UMDF-Based.

Exemplos

O exemplo de código a seguir mostra um segmento da função de retorno de chamada IQueueCallbackDeviceIoControl::OnDeviceIoControl de um driver de porta serial. O segmento de código obtém o buffer de saída da solicitação de E/S e, em seguida, transfere informações de taxa de baud do dispositivo para o buffer.

VOID
STDMETHODCALLTYPE
  CMyQueue::OnDeviceIoControl(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in ULONG ControlCode,
    __in SIZE_T InputBufferSizeInBytes,
    __in SIZE_T OutputBufferSizeInBytes
    )
{
    HRESULT hr;
    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = pWdfRequest;

    switch (ControlCode)
    {
        case IOCTL_SERIAL_GET_BAUD_RATE:
        {
            SERIAL_BAUD_RATE *pBaudRateBuffer;
            hr = pWdfRequest2->RetrieveOutputBuffer(sizeof(SERIAL_BAUD_RATE),
                                                    (PVOID*) &pBaudRateBuffer,
                                                    NULL);
            if (SUCCEEDED(hr))
                  {
                      RtlZeroMemory(pBaudRateBuffer, sizeof(SERIAL_BAUD_RATE));
                      pBaudRateBuffer->BaudRate = m_Device->GetBaudRate();
                      reqCompletionInfo = sizeof(SERIAL_BAUD_RATE);
                  }
            
        }
        break;
        ...
    }
    ...
}

Requisitos

Requisito	Valor
Fim do suporte	Indisponível no UMDF 2.0 e posterior.
Plataforma de Destino	Área de Trabalho
Versão mínima do UMDF	1,9
Cabeçalho	wudfddi.h (inclua Wudfddi.h)
DLL	WUDFx.dll