IWDFDriver：：CreatePreallocatedWdfMemory 方法 (wudfddi.h)

项目
02/27/2024

[警告： UMDF 2 是最新版本的 UMDF，取代了 UMDF 1。所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。未向 UMDF 1 添加新功能，并且较新版本的 Windows 10 上对 UMDF 1 的支持有限。通用 Windows 驱动程序必须使用 UMDF 2。有关详细信息，请参阅使用 UMDF 入门。]

CreatePreallocatedWdfMemory 方法为指定的缓冲区创建框架内存对象。

语法

HRESULT CreatePreallocatedWdfMemory(
  [in]           BYTE       *pBuff,
  [in]           SIZE_T     BufferSize,
  [in, optional] IUnknown   *pCallbackInterface,
  [in, optional] IWDFObject *pParentObject,
  [out]          IWDFMemory **ppWdfMemory
);

参数

[in] pBuff

指向驱动程序为内存对象提供的数据缓冲区的指针。

[in] BufferSize

pBuff 指向的数据的大小（以字节为单位）。

[in, optional] pCallbackInterface

指向 IUnknown 接口的指针，框架使用该接口来确定驱动程序在新创建的内存对象上订阅的对象相关事件回调函数。此参数是可选的。如果驱动程序不需要通知，驱动程序可以传递 NULL 。 IUnknown 接口用于对象清理和处置。如果驱动程序传递有效的指针，框架将在 IObjectCleanup 接口的 IUnknown 接口上调用 QueryInterface。如果框架获取驱动程序的 IObjectCleanup 接口，则框架随后可以调用驱动程序的 IObjectCleanup：：OnCleanup 方法，以通知驱动程序内存对象已清理。

[in, optional] pParentObject

指向所创建内存对象的父对象的 IWDFObject 接口的指针。如果 为 NULL，驱动程序对象将成为默认父对象。

[out] ppWdfMemory

指向缓冲区的指针，该缓冲区接收指向新创建的 WDF 内存对象的 IWDFMemory 接口的指针。

返回值

如果操作成功，CreatePreallocatedWdfMemory 将返回S_OK。否则，此方法返回 Winerror.h 中定义的错误代码之一。

注解

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

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

UMDF 驱动程序调用 CreatePreallocatedWdfMemory 后，驱动程序可以调用 IWDFMemory：：SetBuffer ，将不同的缓冲区分配给 CreatePreallocatedWdfMemory 创建的内存对象。

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

示例

下面的代码示例演示如何为缓冲区创建内存对象。

    //
    // Allocate a request.
    hr = wdfDevice->CreateRequest(NULL, NULL, &request);

    // Allocate a buffer and wrap it in a memory object. 
    // Make the memory object a child of the request. 
    // When the request object is deleted, the memory object 
    // is also deleted. 

    if (SUCCEEDED(hr))
    {
       buffer = new BYTE[m_HidDescriptor->wReportLength];

       if (buffer == NULL)
       {
          hr = E_OUTOFMEMORY;
       }
    }

    if (SUCCEEDED(hr))
    {
       CComPtr<IWDFDriver> driver;
       wdfDevice->GetDriver(&driver);

       hr = driver->CreatePreallocatedWdfMemory(
                       buffer,
                       m_HidDescriptor->wReportLength,
                       NULL,
                       request,
                       &memory
                       );
    }

要求

要求	值
结束支持	在 UMDF 2.0 及更高版本中不可用。
目标平台	桌面
最低 UMDF 版本	1.5
标头	wudfddi.h (包括 Wudfddi.h)
DLL	WUDFx.dll