Edit

WdfRequestProbeAndLockUserBufferForWrite function (wdfrequest.h)

  • Article

[Applies to KMDF only]

The WdfRequestProbeAndLockUserBufferForWrite method verifies that an I/O request's user-mode buffer is writeable, and then it locks the buffer's physical memory pages so drivers in the driver stack can write into the buffer.

Syntax

NTSTATUS WdfRequestProbeAndLockUserBufferForWrite(
  [in]  WDFREQUEST Request,
  [in]  PVOID      Buffer,
  [in]  size_t     Length,
  [out] WDFMEMORY  *MemoryObject
);

Parameters

[in] Request

A handle to a framework request object.

[in] Buffer

A pointer to the request's output buffer. For more information, see the following Remarks section.

[in] Length

The length, in bytes, of the request's output buffer.

[out] MemoryObject

A pointer to a location that receives a handle to a framework memory object that represents the user output buffer.

Return value

WdfRequestProbeAndLockUserBufferForWrite 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_USER_BUFFER
 The Length parameter is zero.
STATUS_INVALID_DEVICE_REQUEST
 The request has already been completed or is otherwise invalid.
STATUS_ACCESS_VIOLATION
 The current thread is not the creator of the I/O request.
STATUS_INSUFFICIENT_RESOURCES
 There is insufficient memory to complete the operation.
 

This method might also return other NTSTATUS values.

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

Remarks

The user output buffer typically receives information that the driver has read from the device.

Only a top-level driver can call the WdfRequestProbeAndLockUserBufferForWrite method, because the method requires the process context of the process that created the I/O request.

The user-mode buffer that the Buffer parameter specifies can be the buffer that WdfRequestRetrieveUnsafeUserOutputBuffer retrieves, or it can be a different user-mode output buffer. For example, an I/O control code that uses the buffered access method might pass a structure that contains an embedded pointer to a user-mode buffer. In such a case, the driver can useWdfRequestProbeAndLockUserBufferForWrite to obtain a memory object for the buffer.

The buffer length that the Length parameter specifies must not be larger than the buffer's actual size. Otherwise, drivers can access memory outside of the buffer, which is a security risk.

If WdfRequestProbeAndLockUserBufferForWrite returns STATUS_SUCCESS, the driver receives a handle to a framework memory object that represents the user-mode buffer. To access the buffer, the driver must call WdfMemoryGetBuffer.

The framework memory object is automatically released when the driver calls WdfRequestComplete.

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

Examples

For a code example that uses WdfRequestProbeAndLockUserBufferForWrite, see WdfRequestProbeAndLockUserBufferForRead.

Requirements

Requirement Value
Target Platform Universal
Minimum KMDF version 1.0
Header wdfrequest.h (include Wdf.h)
Library Wdf01000.sys (see Framework Library Versioning.)
IRQL PASSIVE_LEVEL
DDI compliance rules DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

See also

WdfMemoryGetBuffer

WdfRequestProbeAndLockUserBufferForRead

WdfRequestRetrieveUnsafeUserOutputBuffer