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 が指すバッファーの 0 以外のサイズ (バイト単位)。
[out] Memory
新しいメモリ オブジェクトへのハンドルを受け取る場所へのポインター。
戻り値
操作が成功した場合、WdfMemoryCreatePreallocated はSTATUS_SUCCESSを返します。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。
| リターン コード | 説明 |
|---|---|
|
無効なパラメーターが検出されました。 |
|
メモリが不足していました。 |
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) |