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。 否則，此方法可能會傳回下列其中一個值：
| 回傳碼 | 說明 |
|---|---|
|
偵測到無效的參數。 |
|
記憶體不足。 |
如需 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
);
需求
| 要求 | 價值 |
|---|---|
| 目標平臺 | 普遍 |
| 最低 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） |