WdfRequestRetrieveInputMemory function (wdfrequest.h)

[Applies to KMDF and UMDF]

The WdfRequestRetrieveInputMemory method retrieves a handle to a framework memory object that represents an I/O request's input buffer.

Syntax

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

Parameters

[in] Request

A handle to a framework request object.

[out] Memory

A pointer to a location that receives a handle to a framework memory object.

Return value

WdfRequestRetrieveInputMemory returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:

This method might also return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

A request's input buffer contains information, such as data to be written to a disk, that was supplied by the originator of the request. Your driver can call WdfRequestRetrieveInputMemory to obtain the input buffer for a write request or a device I/O control request, but not for a read request (because read requests do not provide input data).

The WdfRequestRetrieveInputMemory method retrieves the input buffer for I/O requests that use the buffered I/O method or the direct I/O method for accessing data buffers. If the request's I/O control code is IRP_MJ_INTERNAL_DEVICE_CONTROL, or if the request came from another kernel-mode driver, WdfRequestRetrieveInputMemory also supports I/O requests that use neither buffered nor direct I/O.

If WdfRequestRetrieveInputMemory returns STATUS_SUCCESS, the driver receives a handle to a framework memory object that represents the input buffer. To access the buffer, the driver must call WdfMemoryGetBuffer.

The driver can access the retrieved framework memory object until it completes the I/O request that the Request parameter represents.

Instead of calling WdfRequestRetrieveInputMemory, the driver can call WdfRequestRetrieveInputBuffer, which retrieves the buffer's address and length.

For more information about WdfRequestRetrieveInputMemory, see Accessing Data Buffers in Framework-Based Drivers.

Examples

The following code example shows how an EvtIoWrite callback function can obtain a handle to the framework memory object that represents a write request's input buffer. The example then formats and sends the write request to a USB I/O target.

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;
}

Requirements

See also

WdfMemoryGetBuffer

WdfRequestRetrieveInputBuffer

WdfRequestRetrieveOutputMemory