Funzione WdfRequestRetrieveOutputMemory (wdfrequest.h)

[Si applica a KMDF e UMDF]

Il metodo WdfRequestRetrieveOutputMemory recupera un handle in un oggetto di memoria del framework che rappresenta il buffer di output della richiesta di I/O.

Sintassi

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

Parametri

[in] Request

Handle per un oggetto richiesta framework.

[out] Memory

Puntatore a una posizione che riceve un handle a un oggetto memoria del framework.

Valore restituito

WdfRequestRetrieveOutputMemory restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Un parametro di input non è valido.
STATUS_INVALID_DEVICE_REQUEST	Il tipo di richiesta non è valido o la richiesta usa né buffering né I/O diretto. Per altre informazioni sui metodi supportati per l'accesso ai buffer dei dati, vedere la sezione Osservazioni seguenti.
STATUS_INTERNAL_ERROR	La richiesta è già stata completata.
STATUS_BUFFER_TOO_SMALL	La lunghezza del buffer di output è zero.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente.

 

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

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

Il metodo WdfRequestRetrieveOutputMemory recupera il buffer di output per le richieste di I/O che usano il metodo I/O memorizzato nel buffer o il metodo I/O diretto per l'accesso ai buffer dei dati. Se il codice di controllo I/O della richiesta è IRP_MJ_INTERNAL_DEVICE_CONTROL o se la richiesta proviene da un altro driver in modalità kernel, WdfRequestRetrieveOutputMemory supporta anche richieste di I/O che usano né buffer né I/O diretto.

Se WdfRequestRetrieveOutputMemory restituisce STATUS_SUCCESS, il driver riceve un handle a un oggetto memoria del framework che rappresenta il buffer di output. Per accedere al buffer, il driver deve chiamare WdfMemoryGetBuffer.

Il driver può accedere all'oggetto memoria del framework recuperato finché non completa la richiesta di I/O rappresentata dal parametro Request .

Anziché chiamare WdfRequestRetrieveOutputMemory, il driver può chiamare WdfRequestRetrieveOutputBuffer, che recupera l'indirizzo e la lunghezza del buffer.

Per altre informazioni su WdfRequestRetrieveOutputMemory, vedere Accesso ai buffer dei dati in Framework-Based driver.

Esempio

Nell'esempio di codice seguente viene illustrato come una funzione di callback EvtIoRead può ottenere un handle per l'oggetto memoria del framework che rappresenta il buffer di output di una richiesta di lettura. L'esempio formatta e invia la richiesta di lettura a una destinazione di I/O 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;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfrequest.h (include Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regole di conformità 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)

Vedi anche

WdfMemoryGetBuffer

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputBuffer