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
割り当てられたメモリのドライバー定義プール タグ。 デバッガーには、このタグが表示されます。 通常、ドライバーは、一重引用符で区切られた最大 4 文字の文字列を逆の順序 ("dcba" など) で指定します。 タグ内の各文字の ASCII 値は、0 から 127 の間である必要があります。 各プール タグが一意である場合、ドライバーのデバッグが簡単になります。
PoolTag が 0 の場合、フレームワークは、ドライバーのカーネル モード サービス名の最初の 4 文字を使用する既定のプール タグを提供します。 サービス名が "WDF" で始まる場合 (名前は大文字と小文字は区別されず、引用符は含まれません)、次の 4 文字が使用されます。 使用できる文字数が 4 文字未満の場合は、"FxDr" が使用されます。
KMDF バージョン 1.5 以降の場合、ドライバーは WDF_DRIVER_CONFIG 構造体の DriverPoolTag メンバーを使用して、既定のプール タグを指定できます。
[in] BufferSize
バッファーの 0 以外の指定サイズ (バイト単位)。
[out] Memory
新しいメモリ オブジェクトへのハンドルを受け取る場所へのポインター。
[out, optional] Buffer
新しいメモリ オブジェクトに関連付けられているバッファーへのポインターを受け取る場所へのポインター。 このパラメーターは省略可能であり、 NULL にすることができます。
戻り値
WdfMemoryCreate は、操作が成功した場合にSTATUS_SUCCESSを返します。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。
| リターン コード | 説明 |
|---|---|
|
無効なパラメーターが検出されました。 |
|
メモリが不足していました。 |
WdfMemoryCreate メソッドが返す可能性があるその他の戻り値の一覧については、「Framework オブジェクト作成エラー」を参照してください。
このメソッドは、他の NTSTATUS 値を返す場合もあります。
注釈
WdfMemoryCreate メソッドは、BufferSize パラメーターが指定するサイズのバッファーを割り当て、バッファーを表すフレームワーク メモリ オブジェクトを作成します。
バッファーのアドレスを取得するために、ドライバーは WdfMemoryCreate 関数の Buffer パラメーターに NULL 以外の値を指定するか、ドライバーで WdfMemoryGetBuffer を呼び出すことができます。
機密情報の開示を避けるために、特に信頼されていない場所 (ユーザー モード、ネットワーク経由など) にコピーされる割り当てについては、メモリ割り当て用にメモリをゼロにすることをお勧めします。 WdfMemoryCreate は、割り当てられたメモリを既定で初期化しません。
割り当てられたメモリのドライバーの使用パターンに基づいて、ドライバーライターの推奨事項は次のことを考慮することです。
- WdfMemoryCreate を呼び出した直後の RtlZeroMemory
- または、ゼロアロケーション API (カーネル モードの場合は ExAllocatePool2、 ExAllocatePoolZero ) を使用します。 HeapAlloc と、ユーザー モードの HEAP_ZERO_MEMORY フラグ)、その後に WdfMemoryCreatePreallocated が続きます。 事前に割り当てられたバッファーは、WDFMEMORY またはその親の削除の一部として自動的に削除されないため、これは最適な方法ではありません。
各メモリ オブジェクトの既定の親オブジェクトは、 WdfMemoryCreate と呼ばれるドライバーを表すフレームワーク ドライバー オブジェクトです。 ドライバーが特定のデバイス オブジェクト、要求オブジェクト、またはその他のフレームワーク オブジェクトで使用するメモリ オブジェクトを作成する場合は、メモリ オブジェクトの親を適切に設定する必要があります。 親オブジェクトが削除されると、メモリ オブジェクトとそのバッファーが削除されます。 既定の親オブジェクトを変更しない場合、I/O マネージャーがドライバーをアンロードするまで、メモリ オブジェクトとそのバッファーは残ります。
ドライバーは、 WdfObjectDelete を呼び出すことによって、メモリ オブジェクトとそのバッファーを削除することもできます。
BufferSize がPAGE_SIZE未満の場合、オペレーティング システムは呼び出し元に要求されたメモリバイト数を正確に指定します。 バッファーは必ずしもページアラインされるとは限りませんが、MEMORY_ALLOCATION_ALIGNMENT定数が Ntdef.h で指定するバイト数で整列されます。
BufferSize がPAGE_SIZE以上の場合、KMDF の場合、システムはページアラインバッファーのみを割り当てます。 PoolType パラメーターが NonPagedPool の場合、システムはすべてのバイトを保持するために必要なページ数を割り当てます。 最後に割り当てられたページの未使用のバイトはすべて、本質的に無駄になります。
フレームワーク メモリ オブジェクトの詳細については、「メモリ バッファーの使用」を参照してください。
ドライバーで PoolType に PagedPool が指定されている場合は、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
);
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| 最小 KMDF バージョン | 1.0 |
| 最小 UMDF バージョン | 2.0 |
| Header | wdfmemory.h (Wdf.h を含む) |
| Library | Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF) |
| IRQL | 「解説」を参照してください。 |
| DDI コンプライアンス規則 | DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 ParentObjectCheck(kmdf) |