WdfRequestRetrieveInputMemory function (wdfrequest.h)

Article
04/18/2022

[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:

Return code	Description
STATUS_INVALID_PARAMETER	An input parameter is invalid.
STATUS_INVALID_DEVICE_REQUEST	The request type is not valid or the request is using neither buffered nor direct I/O. For more information about supported methods for accessing data buffers, see the following Remarks section.
STATUS_INTERNAL_ERROR	The request has already been completed.
STATUS_BUFFER_TOO_SMALL	The input buffer's length is zero.
STATUS_INSUFFICIENT_RESOURCES	There is insufficient memory.

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

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfrequest.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), InputBufferAPI(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MemAfterReqCompletedIntIoctl(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctl(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedRead(kmdf), MemAfterReqCompletedWrite(kmdf), MemAfterReqCompletedWriteA(kmdf)