WdfMemoryCreatePreallocated 函数 (wdfmemory.h)
[适用于 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。 否则，此方法可能会返回以下值之一：
| 返回代码 | 说明 |
|---|---|
|
检测到参数无效。 |
|
内存不足。 |
有关 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) |