WdfMemoryCreateFromLookaside function (wdfmemory.h)

Article
04/18/2022

[Applies to KMDF only]

The WdfMemoryCreateFromLookaside method creates a framework memory object and obtains a memory buffer from a specified lookaside list.

Syntax

NTSTATUS WdfMemoryCreateFromLookaside(
  [in]  WDFLOOKASIDE Lookaside,
  [out] WDFMEMORY    *Memory
);

Parameters

[in] Lookaside

A handle to a framework lookaside-list object that is obtained by calling WdfLookasideListCreate.

[out] Memory

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

Return value

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

Return code	Description
STATUS_INVALID_PARAMETER	An invalid parameter was detected.
STATUS_INSUFFICIENT_RESOURCES	There was insufficient memory.

This method also might return other NTSTATUS values.

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

Remarks

After your driver calls WdfLookasideListCreate to create a lookaside-list object, the driver can call WdfMemoryCreateFromLookaside to obtain a buffer from the lookaside list.

The framework provides a handle to a memory object that represents the buffer. When the framework creates the memory object, it uses object attributes that the driver supplied when it called WdfMemoryCreateFromLookaside.

When your driver has finished using a memory object that it obtained from a lookaside list, the driver must call WdfObjectDelete to return the memory object to the lookaside list.

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

If lookaside-list buffers are being allocated from the pageable memory pool, the WdfMemoryCreateFromLookaside method must be called at IRQL <= APC_LEVEL. Otherwise, the method can be called at IRQL <= DISPATCH_LEVEL.

Examples

The following code example creates a lookaside list and stores the list's handle in driver-defined device object context space. Then, the driver obtains a buffer from the lookaside list.

PDRIVER_CONTEXT  driverContext;
WDFMEMORY  memHandle;

driverContext = GetDriverContext(driver);

status = WdfLookasideListCreate(
                                WDF_NO_OBJECT_ATTRIBUTES,
                                sizeof(MY_LOOKASIDE_BUFFER),
                                NonPagedPool,
                                WDF_NO_OBJECT_ATTRIBUTES,
                                MY_POOL_TAG,
                                &driverContext->LookasideListHandle
                                );
...
status = WdfMemoryCreateFromLookaside(
                                      driverContext->LookasideListHandle,
                                      &memHandle
                                      );

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Header	wdfmemory.h (include Wdf.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	See Remarks section.
DDI compliance rules	DriverCreate(kmdf)