IWDFDriver：：CreatePreallocatedWdfMemory 方法 (wudfddi.h)

發行項
03/01/2024

[警告： UMDF 2 是最新版的 UMDF，並取代 UMDF 1。所有新的UMDF驅動程式都應該使用UMDF 2撰寫。未將新功能新增至 UMDF 1，且較新版本的 #DDF890EEFF5D34DD4AEDCC73E3CD03D43 上，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 驅動程式必須建立代表既有記憶體緩衝區的記憶體物件，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