Función WdfRequestRetrieveOutputMemory (wdfrequest.h)

[Se aplica a KMDF y UMDF]

El método WdfRequestRetrieveOutputMemory recupera un identificador de un objeto de memoria de marco que representa el búfer de salida de una solicitud de E/S.

Sintaxis

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

Parámetros

[in] Request

Identificador de un objeto de solicitud de marco.

[out] Memory

Puntero a una ubicación que recibe un identificador de un objeto de memoria de marco.

Valor devuelto

WdfRequestRetrieveOutputMemory 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
STATUS_INVALID_PARAMETER	Un parámetro de entrada no es válido.
STATUS_INVALID_DEVICE_REQUEST	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.
STATUS_INTERNAL_ERROR	La solicitud ya se ha completado.
STATUS_BUFFER_TOO_SMALL	La longitud del búfer de salida es cero.
STATUS_INSUFFICIENT_RESOURCES	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 WdfRequestRetrieveOutputMemory 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 WdfRequestRetrieveOutputMemory 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, WdfRequestRetrieveOutputMemory también admite solicitudes de E/S que no usan E /S almacenadas en búfer ni E/S directas.

Si WdfRequestRetrieveOutputMemory devuelve STATUS_SUCCESS, el controlador recibe un identificador de un objeto de memoria de marco que representa el búfer de salida. Para acceder al búfer, el controlador debe llamar a WdfMemoryGetBuffer.

El controlador puede acceder al objeto de memoria del marco recuperado hasta que complete la solicitud de E/S que representa el parámetro Request .

En lugar de llamar a WdfRequestRetrieveOutputMemory, el controlador puede llamar a WdfRequestRetrieveOutputBuffer, que recupera la dirección y la longitud del búfer.

Para obtener más información sobre WdfRequestRetrieveOutputMemory, consulte Acceso a los búferes de datos en controladores de Framework-Based.

Ejemplos

En el ejemplo de código siguiente se muestra cómo una función de devolución de llamada EvtIoRead puede obtener un identificador para el objeto de memoria del marco que representa el búfer de salida de una solicitud de lectura. A continuación, el ejemplo da formato y envía la solicitud de lectura a un destino de E/S 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;
}

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	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)

Consulte también

WdfMemoryGetBuffer

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputBuffer