Metodo IWDFIoRequest2::RetrieveInputMemory (wudfddi.h)

Articolo
08/08/2023

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Nessuna nuova funzionalità viene aggiunta 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 informazioni, vedere Introduzione con UMDF.]

Il metodo RetrieveInputMemory recupera l'interfaccia IWDFMemory di un oggetto di memoria del framework che rappresenta il buffer di input della richiesta di I/O.

Sintassi

HRESULT RetrieveInputMemory(
  [out] IWDFMemory **Memory
);

Parametri

[out] Memory

Indirizzo di una posizione che riceve un puntatore all'interfaccia IWDFMemory di un oggetto memoria UMDF.

Valore restituito

RetrieveInputMemory 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.
E_OUTOFMEMORY	Memoria insufficiente disponibile 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 che Winerror.h contiene.

Commenti

Il buffer di input di una richiesta contiene informazioni, ad esempio i dati da scrivere in un disco, che l'origine della richiesta specificata. Il driver può chiamare RetrieveInputMemory per ottenere il buffer di input per una richiesta di scrittura o una richiesta di controllo I/O del dispositivo, ma non per una richiesta di lettura (perché le richieste di lettura non forniscono dati di input).

Il metodo RetrieveInputMemory recupera il buffer di input per le richieste di I/O che usano il metodo I/O con buffer o I/O diretto per l'accesso ai buffer dei dati.

Se RetrieveInputMemory restituisce S_OK, il driver riceve un puntatore all'interfaccia IWDFMemory di un oggetto di memoria UMDF che rappresenta il buffer di input. Per accedere al buffer, il driver deve chiamare IWDFMemory::GetDataBuffer.

Il driver può accedere all'oggetto memoria del framework recuperato finché non completa la richiesta di I/O. Prima che il driver completi la richiesta di I/O, deve chiamare IWDFMemory::Release.

Anziché chiamare RetrieveInputMemory, il driver può chiamare IWDFIoRequest2::RetrieveInputBuffer, che recupera l'indirizzo e la lunghezza del 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

Nell'esempio di codice seguente viene illustrato come una funzione di callback IQueueCallbackWrite::OnWrite può ottenere l'interfaccia IWDFMemory dell'oggetto memoria del framework che rappresenta il buffer di input di una richiesta di scrittura. L'esempio formatta e invia la richiesta di scrittura a una destinazione di I/O USB.

VOID
STDMETHODCALLTYPE
  CMyQueue::OnWrite(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in SIZE_T BytesToWrite
    )
{
    HRESULT hr = S_OK;
    IWDFMemory * pInputMemory = NULL;
    IWDFUsbTargetPipe * pOutputPipe = m_Device->GetOutputPipe();
    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = pWdfRequest;

    hr = r2->RetrieveInputMemory(&pInputMemory);
    if (FAILED(hr)) goto Exit;

    hr = pOutputPipe->FormatRequestForWrite(
                                           pWdfRequest,
                                           NULL, //pFile
                                           pInputMemory,
                                           NULL, //Memory offset
                                           NULL  //DeviceOffset
                                           );
Exit:
    if (FAILED(hr))
    {
        pWdfRequest->Complete(hr);
    }
    else
    {
        ForwardFormattedRequest(pWdfRequest, pOutputPipe);
    }
    SAFE_RELEASE(pInputMemory);
 return;
}

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