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 版和更新版本，您的驅動程式可以使用 DriverPoolTagWDF_DRIVER_CONFIG 結構的成員來指定預設集區標記。
[in] BufferSize
緩衝區的非零指定大小，以位元組為單位。
[out] Memory
接收新記憶體物件句柄之位置的指標。
[out, optional] Buffer
接收與新記憶體對象相關聯之緩衝區指標之位置的指標。 這個參數是選擇性的，而且可以 NULL。
返回值
如果作業成功，WdfMemoryCreate 會傳回STATUS_SUCCESS。 否則，此方法可能會傳回下列其中一個值：
| 回傳碼 | 說明 |
|---|---|
|
偵測到無效的參數。 |
|
記憶體不足。 |
如需 WdfMemoryCreate 方法可能會傳回的其他傳回值清單，請參閱 Framework 物件建立錯誤。
此方法也可能 傳回其他NTSTATUS 值。
備註
WdfMemoryCreate 方法會配置 BufferSize 參數所指定大小緩衝區，並建立代表緩衝區的架構記憶體物件。
若要取得緩衝區的位址，驅動程式可以為 WdfMemoryCreate 函式的 Buffer 參數提供非NULL 值，或者驅動程式可以呼叫 WdfMemoryGetBuffer。
記憶體配置零記憶體是很好的作法，特別是將複製到不受信任位置的配置（使用者模式、透過網路等）以避免披露敏感性資訊。 WdfMemoryCreate 預設不會將配置的記憶體初始化為零。
根據驅動程式所設定記憶體的使用模式，驅動程式寫入器的建議是考慮：
- RtlZeroMemory 在呼叫 WdfMemoryCreate 後立即
- 或者，針對核心模式使用零配置 API（ExAllocatePool2、ExAllocatePoolZero;HeapAlloc 搭配使用者模式的 HEAP_ZERO_MEMORY 旗標），後面接著 WdfMemoryCreatePreallocated。 由於預先配置的緩衝區不會在WDFMEMORY或其父代刪除時自動刪除，因此這不是最佳方法。
每個記憶體物件的預設父物件是 Framework 驅動程式物件，代表呼叫 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
);
需求
| 要求 | 價值 |
|---|---|
| 目標平臺 | 普遍 |
| 最低 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） |