Funzione WdfRequestRetrieveOutputBuffer (wdfrequest.h)
[Si applica a KMDF e UMDF]
Il metodo WdfRequestRetrieveOutputBuffer recupera il buffer di output di una richiesta di I/O.
Sintassi
NTSTATUS WdfRequestRetrieveOutputBuffer(
[in] WDFREQUEST Request,
[in] size_t MinimumRequiredSize,
[out] PVOID *Buffer,
[out, optional] size_t *Length
);
Parametri
[in] Request
Handle per un oggetto richiesta framework.
[in] MinimumRequiredSize
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
WdfRequestRetrieveOutputBuffer restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:
| Codice restituito | Descrizione |
|---|---|
|
Un parametro di input non è valido. |
|
La lunghezza del buffer di output è zero o il parametro MinimumRequiredSize specifica una dimensione del buffer maggiore delle dimensioni effettive del buffer. |
|
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. |
|
La richiesta è già stata completata. |
|
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 WdfRequestRetrieveOutputBuffer per ottenere il buffer di output per una richiesta di lettura o un controllo di I/O del dispositivo, ma non per una richiesta di scrittura (perché le richieste di scrittura non forniscono dati di output).
Il metodo WdfRequestRetrieveOutputBuffer 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 di I/O della richiesta è IRP_MJ_INTERNAL_DEVICE_CONTROLo se la richiesta proviene da un altro driver in modalità kernel, WdfRequestRetrieveOutputBuffer supporta anche le richieste di I/O che usano i/O memorizzati nel buffer né direttamente.
Se WdfRequestRetrieveOutputBuffer restituisce STATUS_SUCCESS, il driver riceve l'indirizzo e, facoltativamente, le dimensioni del buffer di output.
Il driver può accedere al buffer recuperato fino a quando non completa la richiesta di I/O rappresentata dal parametro request.
Anziché chiamare WdfRequestRetrieveOutputBuffer, il driver può chiamare WdfRequestRetrieveOutputMemory, che crea un oggetto memoria framework che rappresenta il buffer.
Per altre informazioni su WdfRequestRetrieveOutputBuffer, vedere Accesso ai buffer dei dati in driver Framework-Based.
Esempi
L'esempio di codice seguente fa parte di un EvtIoDeviceControl funzione di callback. Questo esempio ottiene il descrittore di configurazione di un dispositivo USB e inserisce il descrittore nel buffer di output della richiesta di I/O.
VOID
MyEvtIoDeviceControl(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN size_t OutputBufferLength,
IN size_t InputBufferLength,
IN ULONG IoControlCode
)
{
WDFDEVICE device;
PDEVICE_CONTEXT pDevContext;
size_t bytesReturned = 0;
NTSTATUS status;
device = WdfIoQueueGetDevice(Queue);
//
// GetDeviceContext is a driver-defined function
// to retrieve device object context space.
//
pDevContext = GetDeviceContext(device);
switch(IoControlCode) {
case IOCTL_OSRUSBFX2_GET_CONFIG_DESCRIPTOR: {
PUSB_CONFIGURATION_DESCRIPTOR configurationDescriptor = NULL;
USHORT requiredSize;
//
// First, get the size of the USB configuration descriptor.
//
status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
pDevContext->UsbDevice,
NULL,
&requiredSize
);
if (status == STATUS_BUFFER_TOO_SMALL) {
break;
}
//
// Get the buffer. Make sure the buffer is big
// enough to hold the configuration descriptor.
//
status = WdfRequestRetrieveOutputBuffer(
Request,
(size_t)requiredSize,
&configurationDescriptor,
NULL
);
if(!NT_SUCCESS(status)){
break;
}
//
// Now get the config descriptor.
//
status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
pDevContext->UsbDevice,
configurationDescriptor,
&requiredSize
);
if (!NT_SUCCESS(status)) {
break;
}
bytesReturned = requiredSize;
}
break;
...
(Other case statements removed.)
...
default:
status = STATUS_INVALID_DEVICE_REQUEST;
break;
}
//
// Complete the request.
//
WdfRequestCompleteWithInformation(
Request,
status,
bytesReturned
);
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 | BufAfterReqCompletedIntIoctl(kmdf), BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctl() kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedRead(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWrite(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), Non validoReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), outputBufferAPI(kmdf) |