WdfMemoryCreatePreallocated 函式 (wdfmemory.h)

發行項
02/29/2024

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

如需 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)