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 が指すバッファーの 0 以外のサイズ (バイト単位)。

[out] Memory

新しいメモリオブジェクトへのハンドルを受け取る場所へのポインター。

戻り値

操作が成功した場合、WdfMemoryCreatePreallocated はSTATUS_SUCCESSを返します。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_INSUFFICIENT_RESOURCES	メモリが不足していました。

WdfMemoryCreatePreallocated メソッドが返す可能性があるその他の戻り値の一覧については、「フレームワークオブジェクト作成エラー」を参照してください。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

注釈

WdfMemoryCreatePreallocated メソッドは、ドライバーが以前に割り当てたり取得したりしたバッファーのフレームワークメモリオブジェクトを作成します。

既存のメモリバッファーを表すメモリオブジェクトを作成する必要がある場合、ドライバーは WdfMemoryCreatePreallocated を呼び出すことができます。たとえば、ドライバーは、内部 I/O 制御コードを含む I/O 要求のバッファー内でドライバー定義構造体を受け取る場合があります。ドライバーは WdfMemoryCreatePreallocated を呼び出して、ドライバーが I/O ターゲットに構造体を渡すことができるようにメモリオブジェクトを作成できます。

ドライバーが WdfMemoryCreatePreallocated を呼び出した後、ドライバーは WdfMemoryAssignBuffer を呼び出して、 WdfMemoryCreatePreallocated によって作成されたメモリオブジェクトに別のバッファーを割り当てることができます。

各メモリオブジェクトの既定の親オブジェクトは、 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
Header	wdfmemory.h (Wdf.h を含む)
Library	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)