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
                                     );

要件

こちらもご覧ください

ExAllocatePoolWithTag

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT

WdfMemoryAssignBuffer

WdfMemoryCreate

WdfMemoryCreateFromLookaside