WdfMemoryCreatePreallocated 函式 (wdfmemory.h)
[適用於 KMDF 和 UMDF]
WdfMemoryCreatePreallocated 方法會為驅動程式提供的記憶體緩衝區建立架構記憶體物件。
語法
NTSTATUS WdfMemoryCreatePreallocated(
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[in] __drv_aliasesMem PVOID Buffer,
[in] size_t BufferSize,
[out] WDFMEMORY *Memory
);
參數
[in, optional] Attributes
包含新記憶體物件之物件屬性 之WDF_OBJECT_ATTRIBUTES 結構的指標。 這個參數是選擇性的，而且可以WDF_NO_OBJECT_ATTRIBUTES。
[in] Buffer
驅動程式提供的緩衝區指標。
[in] BufferSize
Buffer 指向之緩衝區的非零大小，以位元組為單位。
[out] Memory
接收新記憶體物件句柄之位置的指標。
傳回值
如果作業成功，WdfMemoryCreatePreallocated 會傳回STATUS_SUCCESS。 否則，這個方法可能會傳回下列其中一個值：
| 傳回碼 | Description |
|---|---|
|
偵測到無效的參數。 |
|
記憶體不足。 |
如需 WdfMemoryCreatePreallocated 方法可能會傳回的其他傳回值清單，請參閱 Framework 物件建立錯誤。
這個方法也可能傳回其他 NTSTATUS值。
備註
WdfMemoryCreatePreallocated 方法會為驅動程式先前已配置或取得的緩衝區建立架構記憶體物件。
如果您需要建立代表既有記憶體緩衝區的記憶體對象，驅動程式可以呼叫 WdfMemoryCreatePreallocated 。 例如，驅動程式可能會收到緩衝區內包含內部 I/O 控制項程式代碼之 I/O 要求的驅動程式定義結構。 驅動程式可以呼叫 WdfMemoryCreatePreallocated 來建立記憶體物件，讓驅動程式可以將結構傳遞至 I/O 目標。
在驅動程式呼叫 WdfMemoryCreatePreallocated 之後，驅動程式可以呼叫 WdfMemoryAssignBuffer ，將不同的緩衝區指派給 WdfMemoryCreatePreallocated 所 建立的記憶體物件。
每個記憶體對象的默認父物件是 Framework 驅動程式物件，代表名為 WdfMemoryCreatePreallocated 的驅動程式。 如果您的驅動程式建立與特定裝置物件、要求物件或其他架構物件搭配使用的記憶體物件，它應該適當地設定記憶體物件的父代。 刪除父物件時，將會刪除記憶體物件。 如果您未變更預設父物件，則記憶體物件會保留在記憶體中，直到 I/O 管理員卸除您的驅動程序為止。
驅動程式也可以藉由呼叫 WdfObjectDelete 來刪除記憶體物件。
刪除 WdfMemoryCreatePreallocated 所 建立的架構記憶體物件時，架構不會解除分配預先存在的緩衝區。 同樣地， 對 WdfMemoryAssignBuffer 的呼叫不會解除分配先前指派的緩衝區。
如需架構記憶體物件的詳細資訊，請參閱 使用記憶體緩衝區。
範例
下列程式代碼範例會配置緩衝區，然後為緩衝區建立架構記憶體物件。
PVOID pBuffer = NULL;
WDF_OBJECT_ATTRIBUTES attributes;
WDFMEMORY memHandle;
pBuffer = ExAllocatePoolWithTag(
NonPagedPool,
MY_BUFFER_SIZE,
MY_DRIVER_TAG
);
if (pBuffer == NULL){
goto Error;
}
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;
status = WdfMemoryCreatePreallocated(
&attributes,
pBuffer,
MY_BUFFER_SIZE,
&memHandle
);
規格需求
| 需求 | 值 |
|---|---|
| 目標平台 | Universal |
| 最低 KMDF 版本 | 1.0 |
| 最低UMDF版本 | 2.0 |
| 標頭 | wdfmemory.h (包含 Wdf.h) |
| 程式庫 | Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| DDI 合規性規則 | BufAfterReqCompletedIntIoctlA (kmdf) 、 BufAfterReqCompletedIoctlA (kmdf) 、 BufAfterReqCompletedReadA (kmdf) 、 BufAfterReqCompletedWriteA (kmdf) ， DriverCreate (kmdf) ， KmdfIrql (kmdf) ， KmdfIrql2 (kmdf) ， KmdfIrqlExplicit (kmdf) |