WdfMemoryCreatePreallocated 函数 (wdfmemory.h)

项目
02/27/2024

[适用于 KMDF 和 UMDF]

WdfMemoryCreatePreallocated 方法为驱动程序提供的内存缓冲区创建框架内存对象。

语法

NTSTATUS WdfMemoryCreatePreallocated(
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]           __drv_aliasesMem PVOID Buffer,
  [in]           size_t                 BufferSize,
  [out]          WDFMEMORY              *Memory
);

参数

[in, optional] Attributes

指向包含新内存对象的对象属性的WDF_OBJECT_ATTRIBUTES 结构的指针。此参数是可选的，可以WDF_NO_OBJECT_ATTRIBUTES。

[in] Buffer

指向驱动程序提供的缓冲区的指针。

[in] BufferSize

Buffer 指向的缓冲区的非零大小（以字节为单位）。

[out] Memory

指向接收新内存对象的句柄的位置的指针。

返回值

如果操作成功，WdfMemoryCreatePreallocated 将返回STATUS_SUCCESS。否则，此方法可能会返回以下值之一：

返回代码	说明
STATUS_INVALID_PARAMETER	检测到参数无效。
STATUS_INSUFFICIENT_RESOURCES	内存不足。

有关 WdfMemoryCreatePreallocated 方法可能返回的其他返回值的列表，请参阅框架对象创建错误。

此方法还可能返回其他 NTSTATUS 值。

注解

WdfMemoryCreatePreallocated 方法为驱动程序之前分配或获取的缓冲区创建框架内存对象。

如果需要创建表示预先存在的内存缓冲区的内存对象，驱动程序可以调用 WdfMemoryCreatePreallocated 。例如，驱动程序可能会在包含内部 I/O 控制代码的 I/O 请求的缓冲区内接收驱动程序定义的结构。驱动程序可以调用 WdfMemoryCreatePreallocated 来创建内存对象，以便驱动程序可以将结构传递给 I/O 目标。

驱动程序调用 WdfMemoryCreatePreallocated 后，驱动程序可以调用 WdfMemoryAssignBuffer ，以将不同的缓冲区分配给 WdfMemoryCreatePreallocated 创建的内存对象。

每个内存对象的默认父对象是表示调用 WdfMemoryCreatePreallocated 的驱动程序的框架驱动程序对象。如果驱动程序创建的内存对象与特定的设备对象、请求对象或其他框架对象一起使用，则应相应地设置内存对象的父对象。删除父对象时，将删除内存对象。如果不更改默认父对象，内存对象将保留在内存中，直到 I/O 管理器卸载驱动程序。

驱动程序还可以通过调用 WdfObjectDelete 来删除内存对象。

删除 WdfMemoryCreatePreallocated 创建的框架内存对象时，框架不会解除分配预先存在的缓冲区。同样，调用 WdfMemoryAssignBuffer 不会解除分配以前分配的缓冲区。

有关框架内存对象的详细信息，请参阅使用内存缓冲区。

示例

下面的代码示例分配一个缓冲区，然后为该缓冲区创建一个框架内存对象。

PVOID  pBuffer = NULL;
WDF_OBJECT_ATTRIBUTES  attributes;
WDFMEMORY  memHandle;

pBuffer = ExAllocatePoolWithTag(
                                NonPagedPool,
                                MY_BUFFER_SIZE,
                                MY_DRIVER_TAG
                                );
if (pBuffer == NULL){
    goto Error;
}
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;

status = WdfMemoryCreatePreallocated(
                                     &attributes,
                                     pBuffer,
                                     MY_BUFFER_SIZE,
                                     &memHandle
                                     );

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.0
最低 UMDF 版本	2.0
标头	wdfmemory.h (包括 Wdf.h)
Library	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI 符合性规则	BufAfterReqCompletedIntIoctlA (kmdf) ， BufAfterReqCompletedIoctlA (kmdf) ， BufAfterReqCompletedReadA (kmdf) ， BufAfterReqCompletedWriteA (kmdf) 、 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)