Funzione WdfRequestRetrieveInputBuffer (wdfrequest.h)

Articolo
03/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfRequestRetrieveInputBuffer recupera un buffer di input della richiesta di I/O.

Sintassi

NTSTATUS WdfRequestRetrieveInputBuffer(
  [in]            WDFREQUEST Request,
                  size_t     MinimumRequiredLength,
  [out]           PVOID      *Buffer,
  [out, optional] size_t     *Length
);

Parametri

[in] Request

Handle per un oggetto richiesta framework.

MinimumRequiredLength

Dimensioni minime del buffer, in byte, che il driver deve elaborare la richiesta di I/O.

[out] Buffer

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

[out, optional] Length

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

Valore restituito

WdfRequestRetrieveInputBuffer 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_BUFFER_TOO_SMALL	La lunghezza del buffer di input è zero o il parametro MinimumRequiredSize specifica una dimensione del buffer maggiore rispetto alla dimensione effettiva del buffer.
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_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 input di una richiesta contiene informazioni, ad esempio i dati da scrivere in un disco, forniti dall'origine della richiesta. Il driver può chiamare WdfRequestRetrieveInputBuffer 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 WdfRequestRetrieveInputBuffer recupera il buffer di input 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, WdfRequestRetrieveInputBuffer supporta anche le richieste di I/O che usano né buffer né I/O diretto.

Se WdfRequestRetrieveInputBuffer restituisce STATUS_SUCCESS, il driver riceve l'indirizzo e, facoltativamente, le dimensioni del buffer di input.

Il driver può accedere al buffer recuperato finché non completa la richiesta di I/O rappresentata dal parametro Request .

Anziché chiamare WdfRequestRetrieveInputBuffer, il driver può chiamare WdfRequestRetrieveInputMemory, che crea un oggetto di memoria del framework che rappresenta il buffer.

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

Esempio

L'esempio di codice seguente fa parte della funzione di callback EvtIoDeviceControl del driver di esempio seriale. Se il codice di controllo I/O è IOCTL_SERIAL_SET_TIMEOUT, il driver ottiene nuovi valori di timeout dal buffer di input della richiesta di I/O.

VOID
SerialEvtIoDeviceControl(
    IN WDFQUEUE     Queue,
    IN WDFREQUEST   Request,
    IN size_t       OutputBufferLength,
    IN size_t       InputBufferLength,
    IN ULONG        IoControlCode
    )
{
    PVOID  buffer;
    size_t  bufSize;

    switch (IoControlCode) {
...

        case IOCTL_SERIAL_SET_TIMEOUTS: {

            PSERIAL_TIMEOUTS NewTimeouts;

            Status = WdfRequestRetrieveInputBuffer(
                                                   Request,
                                                   sizeof(SERIAL_TIMEOUTS),
                                                   &buffer,
                                                   &bufSize
                                                   );
            if (!NT_SUCCESS(Status)) {
                break;
            }

            NewTimeouts =(PSERIAL_TIMEOUTS)buffer;
    }
...
}

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	BufAfterReqCompletedIntIoctl(kmdf), BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctl(kmdf), BufAfterReqCompletedIoctlA(kmdf),, BufAfterReqCompletedRead(kmdf), BufAfterReqCompletedWrite(kmdf), BufAfterReqCompletedWriteA(kmdf), DriverCreate(kmdf), InputBufferAPI(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal (kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Vedi anche

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputBuffer

WdfUsbTargetDeviceRetrieveConfigDescriptor

Condividi tramite