Funzione WdfRequestRetrieveOutputMemory (wdfrequest.h)

[Si applica a KMDF e UMDF]

Il metodo WdfRequestRetrieveOutputMemory recupera un handle in un oggetto memoria framework che rappresenta il buffer di output di una 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 per 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é memorizzato nel buffer né nell'I/O diretto. Per altre informazioni sui metodi supportati per l'accesso ai buffer di dati, vedere la sezione Osservazioni seguente.
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 può anche restituire altri valori NTSTATUS .

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Osservazioni

Il buffer di output di una richiesta riceve informazioni, ad esempio dati da un disco, che il driver fornisce all'originatore 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 di I/O memorizzato nel buffer o il metodo di I/O diretto per l'accesso ai buffer di dati. Se il codice di controllo I/O della richiesta è IRP_MJ_INTERNAL_DEVICE_CONTROLo se la richiesta proviene da un altro driver in modalità kernel, WdfRequestRetrieveOutputMemory supporta anche le richieste di I/O che usano né memorizzati nel buffer néI/O diretti.

Se WdfRequestRetrieveOutputMemory restituisce STATUS_SUCCESS, il driver riceve un handle per un oggetto memoria 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 fino a quando non completa la richiesta di I/O rappresentata dal parametro richiesta.

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 di dati in driver Framework-Based.

Esempi

L'esempio di codice seguente illustra come una EvtIoRead funzione di callback può ottenere un handle per l'oggetto memoria 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;
}

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.0
versione minima di UMDF	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)

Vedere anche

WdfMemoryGetBuffer

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputBuffer