共用方式為


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
STATUS_INVALID_PARAMETER
偵測到無效的參數。
STATUS_INSUFFICIENT_RESOURCES
記憶體不足。
 

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

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

備註

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

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

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

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

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

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

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

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

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

如果您的驅動程式指定了 PoolTypePagedPool,則必須在 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)

另請參閱

POOL_TYPE

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT

WdfMemoryCreateFromLo在side

WdfMemoryCreatePreallocated

WdfMemoryGetBuffer

WdfObjectDelete