WdfMemoryCreate 函式 (wdfmemory.h)
[適用於 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 |
|---|---|
|
偵測到無效的參數。 |
|
記憶體不足。 |
如需 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) |