IWDFDriver：：CreatePreallocatedWdfMemory 方法（wudfddi.h）

發行項
02/07/2025

[警告： 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