Funzione WdfRequestRetrieveInputMemory (wdfrequest.h)

Articolo
02/27/2024

[Si applica a KMDF e UMDF]

Il metodo WdfRequestRetrieveInputMemory recupera un handle in un oggetto memoria del framework che rappresenta il buffer di input di una richiesta di I/O.

Sintassi

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

Parametri

[in] Request

Handle per un oggetto richiesta del framework.

[out] Memory

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

Valore restituito

WdfRequestRetrieveInputMemory 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 non usa né il buffering né l'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 input è zero.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente.

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

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

Commenti

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

Il metodo WdfRequestRetrieveInputMemory recupera il buffer di input 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 di I/O della richiesta è IRP_MJ_INTERNAL_DEVICE_CONTROL o se la richiesta proviene da un altro driver in modalità kernel, WdfRequestRetrieveInputMemory supporta anche le richieste di I/O che non usano i/O memorizzati nel buffer né diretti.

Se WdfRequestRetrieveInputMemory restituisce STATUS_SUCCESS, il driver riceve un handle per un oggetto memoria framework che rappresenta il buffer di input. 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 Request .

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

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

Esempio

Nell'esempio di codice seguente viene illustrato come una funzione di callback EvtIoWrite può ottenere un handle per l'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 
MyEvtIoWrite(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    NTSTATUS  status;
    WDFUSBPIPE  pipe;
    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->BulkWritePipe;

    //
    // Get input memory.
    //
    status = WdfRequestRetrieveInputMemory(
                                           Request,
                                           &reqMemory
                                           );
    if(!NT_SUCCESS(status)){
        goto Exit;
    }

    //
    // Format the request.
    //
    status = WdfUsbTargetPipeFormatRequestForWrite(
                                          pipe,
                                          Request,
                                          reqMemory,
                                          NULL
                                          );
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestWriteCompletionRoutine,
                                   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), InputBufferAPI(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MemAfterReqCompletedIntIoctl(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctl(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedRead(kmdf), MemAfterReqCompletedWrite(kmdf) , MemAfterReqCompletedWriteA(kmdf)

Vedi anche

WdfMemoryGetBuffer

WdfRequestRetrieveInputBuffer

WdfRequestRetrieveOutputMemory

Condividi tramite