Función WdfRequestRetrieveOutputBuffer (wdfrequest.h)
[Se aplica a KMDF y UMDF]
El método WdfRequestRetrieveOutputBuffer recupera el búfer de salida de una solicitud de E/S.
Sintaxis
NTSTATUS WdfRequestRetrieveOutputBuffer(
[in] WDFREQUEST Request,
[in] size_t MinimumRequiredSize,
[out] PVOID *Buffer,
[out, optional] size_t *Length
);
Parámetros
[in] Request
Identificador de un objeto de solicitud de marco.
[in] MinimumRequiredSize
Tamaño mínimo del búfer, en bytes, que el controlador necesita para procesar la solicitud de E/S.
[out] Buffer
Puntero a una ubicación que recibe la dirección del búfer.
[out, optional] Length
Puntero a una ubicación que recibe el tamaño del búfer, en bytes. Este parámetro es opcional y puede ser NULL.
Valor devuelto
WdfRequestRetrieveOutputBuffer devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método podría devolver uno de los siguientes valores:
| Código devuelto | Descripción |
|---|---|
|
Un parámetro de entrada no es válido. |
|
La longitud del búfer de salida es cero o el parámetro MinimumRequiredSize especifica un tamaño de búfer mayor que el tamaño real del búfer. |
|
El tipo de solicitud no es válido o la solicitud no usa ni E/S almacenada en búfer ni directa. Para obtener más información sobre los métodos admitidos para acceder a los búferes de datos, consulte la sección Comentarios siguientes. |
|
La solicitud ya se ha completado. |
|
No hay memoria suficiente. |
Este método también podría devolver otros valores NTSTATUS.
Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.
Comentarios
El búfer de salida de una solicitud recibe información, como los datos de un disco, que el controlador proporciona al autor de la solicitud. El controlador puede llamar a WdfRequestRetrieveOutputBuffer para obtener el búfer de salida de una solicitud de lectura o una solicitud de control de E/S de dispositivo, pero no para una solicitud de escritura (porque las solicitudes de escritura no proporcionan datos de salida).
El método WdfRequestRetrieveOutputBuffer recupera el búfer de salida para las solicitudes de E/S que usan el método de E/S almacenado en búfer o el método de E/S directa para acceder a los búferes de datos. Si el código de control de E/S de la solicitud es IRP_MJ_INTERNAL_DEVICE_CONTROL, o si la solicitud procede de otro controlador en modo kernel, WdfRequestRetrieveOutputBuffer también admite solicitudes de E/S que usan ni E/S almacenadas en búfer ni E/S directas.
Si WdfRequestRetrieveOutputBuffer devuelve STATUS_SUCCESS, el controlador recibe la dirección y, opcionalmente, el tamaño del búfer de salida.
El controlador puede acceder al búfer recuperado hasta que complete la solicitud de E/S que representa el parámetro Request .
En lugar de llamar a WdfRequestRetrieveOutputBuffer, el controlador puede llamar a WdfRequestRetrieveOutputMemory, que crea un objeto de memoria de marco que representa el búfer.
Para obtener más información sobre WdfRequestRetrieveOutputBuffer, consulte Acceso a los búferes de datos en controladores de Framework-Based.
Ejemplos
El siguiente ejemplo de código forma parte de una función de devolución de llamada EvtIoDeviceControl . En este ejemplo se obtiene el descriptor de configuración de un dispositivo USB y se coloca el descriptor en el búfer de salida de la solicitud de E/S.
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;
}
Requisitos
| Requisito | Value |
|---|---|
| Plataforma de destino | Universal |
| Versión mínima de KMDF | 1.0 |
| Versión mínima de UMDF | 2.0 |
| Encabezado | wdfrequest.h (incluir Wdf.h) |
| Library | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| Reglas de cumplimiento de DDI | BufAfterReqCompletedIntIoctl(kmdf), BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctl(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedRead(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWrite(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), OutputBufferAPI(kmdf) |