WdfMemoryAssignBuffer function (wdfmemory.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfMemoryAssignBuffer method assigns a specified buffer to a memory object that a driver created by calling WdfMemoryCreatePreallocated.

Syntax

NTSTATUS WdfMemoryAssignBuffer(
  [in] WDFMEMORY Memory,
  [in] PVOID     Buffer,
  [in] size_t    BufferSize
);

Parameters

[in] Memory

A handle to a framework memory object that was obtained by calling WdfMemoryCreatePreallocated.

[in] Buffer

A pointer to a driver-supplied buffer.

[in] BufferSize

The nonzero size, in bytes, of the buffer that Buffer points to.

Return value

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

Return code	Description
STATUS_INVALID_PARAMETER	An invalid parameter was detected.

This method also might return other NTSTATUS values.

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

Remarks

The method can assign a buffer to a memory object that WdfMemoryCreatePreallocated created, but not to a memory object that WdfMemoryCreate created.

The buffer that the Buffer parameter points to can be allocated from the pageable or non-pageable memory pool. If the driver allocates the buffer from the pageable pool, or if the buffer is from pageable pool because it came from a user-mode application, the driver must access the buffer only at IRQL < DISPATCH_LEVEL. (Note that the driver's EvtCleanupCallback and EvtDestroyCallback callback functions, if provided, can be called at IRQL <= DISPATCH_LEVEL.)

For more information about framework memory objects, see Using Memory Buffers.

Examples

The following code example allocates a buffer and then assigns the buffer to a framework memory object.

PVOID  pNewBuffer = NULL;

pNewBuffer = ExAllocatePoolWithTag(
                                   NonPagedPool,
                                   NEW_BUFFER_SIZE,
                                   MY_DRIVER_TAG
                                   );
if (pNewBuffer == NULL){
    goto Error;
}

status = WdfMemoryAssignBuffer(
                               memHandle,
                               pNewBuffer,
                               NEW_BUFFER_SIZE
                               );

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfmemory.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	Any level
DDI compliance rules	BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWriteA(kmdf), DriverCreate(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedReadA(kmdf), MemAfterReqCompletedWriteA(kmdf)

Share via