WdfMemoryCreate 函式 (wdfmemory.h)

發行項
02/29/2024

[適用於 KMDF 和 UMDF]

WdfMemoryCreate 方法會建立架構記憶體物件，並配置指定大小的記憶體緩衝區。

語法

NTSTATUS WdfMemoryCreate(
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]            POOL_TYPE              PoolType,
  [in, optional]  ULONG                  PoolTag,
  [in]            size_t                 BufferSize,
  [out]           WDFMEMORY              *Memory,
  [out, optional] PVOID                  *Buffer
);

參數

[in, optional] Attributes

包含新記憶體物件之物件屬性之WDF_OBJECT_ATTRIBUTES 結構的指標。這個參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。

[in] PoolType

POOL_TYPE型別值，指定要配置的記憶體類型。

[in, optional] PoolTag

已配置記憶體的驅動程式定義集區標籤。調試程式會顯示此標記。驅動程式通常會以反向順序 (指定最多四個字元的字元字串，並以單引號分隔，例如 'dcba') 。標記中每個字元的 ASCII 值必須介於 0 到 127 之間。如果每個集區標籤是唯一的，偵錯驅動程式會比較容易。

如果 PoolTag 為零，架構會提供預設集區標籤，使用驅動程式內核模式服務名稱的前四個字元。如果服務名稱以「WDF」開頭， (名稱不區分大小寫，且不包含引號) ，則會使用接下來的四個字元。如果可用的字元少於四個字元，則會使用「FxDr」。。

針對 KMDF 1.5 版和更新版本，您的驅動程式可以使用 WDF_DRIVER_CONFIG 結構的 DriverPoolTag 成員來指定預設集區卷標。

[in] BufferSize

緩衝區的非零指定大小，以位元組為單位。

[out] Memory

接收新記憶體物件句柄之位置的指標。

[out, optional] Buffer

接收與新記憶體對象相關聯之緩衝區指標之位置的指標。這個參數是選擇性的，而且可以是 NULL。

傳回值

如果作業成功，WdfMemoryCreate 會傳回STATUS_SUCCESS。否則，這個方法可能會傳回下列其中一個值：

傳回碼	Description
STATUS_INVALID_PARAMETER	偵測到無效的參數。
STATUS_INSUFFICIENT_RESOURCES	記憶體不足。

如需 WdfMemoryCreate 方法可能會傳回的其他傳回值清單，請參閱 Framework 物件建立錯誤。

這個方法也可能傳回其他 NTSTATUS值。

備註

WdfMemoryCreate 方法會配置 BufferSize 參數所指定大小的緩衝區，並建立代表緩衝區的架構記憶體物件。

若要取得緩衝區的位址，您的驅動程式可以為 WdfMemoryCreate 函式的 Buffer 參數提供非 NULL 值，或者驅動程式可以呼叫 WdfMemoryGetBuffer。

最好不要記憶體配置記憶體，特別是針對將複製到不受信任位置的配置， (使用者模式、透過網路等 ) 來避免揭露敏感性資訊。 WdfMemoryCreate 預設不會零初始化配置的記憶體。

根據驅動程式的已設定記憶體使用模式，驅動程式寫入器的建議是考慮：

呼叫 WdfMemoryCreate 之後，緊接在 RtlZeroMemory 之後
或者，使用零配置 API (ExAllocatePool2、ExAllocatePoolZero 作為核心模式;具有使用者模式) HEAP_ZERO_MEMORY 旗標的 HeapAlloc，後面接著 WdfMemoryCreatePreallocated。因為預先配置的緩衝區不會在WDFMEMORY或其父系刪除時自動刪除，所以這不是最佳方法。

每個記憶體物件的預設父對像是架構驅動程序物件，代表名為 WdfMemoryCreate 的驅動程式。如果您的驅動程式建立與特定裝置物件、要求物件或其他架構物件搭配使用的記憶體物件，它應該適當地設定記憶體物件的父代。刪除父物件時，將會刪除記憶體物件及其緩衝區。如果您未變更預設父物件，則記憶體物件及其緩衝區會保留，直到 I/O 管理員卸除驅動程序為止。

驅動程式也可以藉由呼叫 WdfObjectDelete 來刪除記憶體物件及其緩衝區。

如果 BufferSize 小於PAGE_SIZE，操作系統會提供呼叫端確切要求的記憶體位元組數目。緩衝區不一定是頁面對齊，但會依MEMORY_ALLOCATION_ALIGNMENT常數在 Ntdef.h 中指定的位元組數目對齊。

如果 BufferSize 是PAGE_SIZE或更新版本，則只有 KMDF 系統會配置頁面對齊的緩衝區。如果 PoolType 參數為 NonPagedPool，系統會配置保留所有位元組所需的頁數。最後配置頁面上任何未使用的位元組基本上會浪費。

如需架構記憶體物件的詳細資訊，請參閱使用記憶體緩衝區。

如果您的驅動程式指定了 PoolType 的 PagedPool，則必須在 IRQL <= APC_LEVEL呼叫 WdfMemoryCreate 方法。否則，可以在 IRQL <= DISPATCH_LEVEL呼叫方法。

範例

下列程式代碼範例會建立架構記憶體物件，並配置大小為WRITE_BUFFER_SIZE的緩衝區。記憶體物件的父代是要求物件。

NTSTATUS  status;
WDF_OBJECT_ATTRIBUTES  attributes;
WDFMEMORY  writeBufferMemHandle;
PVOID  writeBufferPointer;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         0,
                         WRITE_BUFFER_SIZE,
                         &writeBufferMemHandle,
                         &writeBufferPointer
                         );

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
最低UMDF版本	2.0
標頭	wdfmemory.h (包含 Wdf.h)
程式庫	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	請參閱一節。
DDI 合規性規則	DriverCreate (kmdf) ， KmdfIrql (kmdf) ， KmdfIrql2 (kmdf) ， KmdfIrqlExplicit (kmdf) ， ParentObjectCheck (kmdf)