WdfRequestRetrieveInputMemory method

[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

Request [in]

A handle to a framework request object.

Memory [out]

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

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, InputBufferAPI, InvalidReqAccess, InvalidReqAccessLocal, KmdfIrql, KmdfIrql2, MemAfterReqCompletedIntIoctl, MemAfterReqCompletedIntIoctlA, MemAfterReqCompletedIoctl, MemAfterReqCompletedIoctlA, MemAfterReqCompletedRead, MemAfterReqCompletedWrite, MemAfterReqCompletedWriteA

See also

WdfMemoryGetBuffer
WdfRequestRetrieveInputBuffer
WdfRequestRetrieveOutputMemory

 

 

Send comments about this topic to Microsoft

Show: