Metodo IWDFIoRequest2::RetrieveOutputBuffer (wudfddi.h)

Articolo
03/05/2024

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Non vengono aggiunte nuove funzionalità a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre info, vedi Introduzione con UMDF.]

Il metodo RequestRetrieveOutputBuffer recupera il buffer di output di una richiesta di I/O.

Sintassi

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

Parametri

[in] MinimumRequiredCb

Dimensioni minime del buffer, in byte, che il driver deve elaborare la richiesta di I/O. Questo valore può essere zero se non sono presenti dimensioni minime del buffer.

[out] Buffer

Puntatore a una posizione che riceve l'indirizzo del buffer.

[out, optional] BufferCb

Puntatore a una posizione che riceve le dimensioni del buffer, in byte. Questo parametro è facoltativo e può essere NULL.

Valore restituito

RequestRetrieveOutputBuffer restituisce S_OK se l'operazione ha esito positivo. In caso contrario, questo metodo può restituire il valore seguente:

Codice restituito	Descrizione
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	La richiesta di I/O non ha fornito un buffer di output o le dimensioni del buffer di output sono inferiori alle dimensioni minime specificate da MinimumRequiredCb .
E_OUTOFMEMORY	Memoria insufficiente per recuperare il buffer. Il driver deve completare la richiesta con un valore di stato di errore.

Questo metodo potrebbe restituire uno degli altri valori contenuti da Winerror.h.

Commenti

Il buffer di output di una richiesta riceve informazioni, ad esempio dati da un disco, che il driver fornisce all'origine della richiesta. Il driver può chiamare RequestRetrieveOutputBuffer per ottenere il buffer di output per una richiesta di lettura o una richiesta di controllo di I/O del dispositivo, ma non per una richiesta di scrittura (perché le richieste di scrittura non forniscono dati di output).

Il metodo RequestRetrieveOutputBuffer recupera il buffer di output per le richieste di I/O che usano il metodo di I/O memorizzato nel buffer o il metodo di I/O diretto per l'accesso ai buffer di dati.

Se RequestRetrieveOutputBuffer restituisce S_OK, il driver riceve l'indirizzo e, facoltativamente, le dimensioni del buffer di output.

Il driver può accedere al buffer recuperato fino a quando non completa la richiesta di I/O.

Anziché chiamare RequestRetrieveOutputBuffer, il driver può chiamare IWDFIoRequest2::RetrieveOutputMemory, che crea un oggetto memoria framework che rappresenta il buffer.

Per altre informazioni sull'accesso ai buffer di dati di una richiesta di I/O, vedere Accesso ai buffer dei dati in UMDF-Based driver.

Esempio

L'esempio di codice seguente mostra un segmento della funzione di callback IQueueCallbackDeviceIoControl::OnDeviceIoControl di un driver seriale. Il segmento di codice ottiene il buffer di output della richiesta di I/O e quindi trasferisce le informazioni sulla velocità in baud dal dispositivo al 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;
        ...
    }
    ...
}

Requisiti

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
Piattaforma di destinazione	Desktop
Versione UMDF minima	1,9
Intestazione	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll