フレームワーク ファイル オブジェクト
アプリケーションまたはドライバーが (通常はファイルを作成または開くことで) デバイスへのアクセスを試みると、オペレーティング システムはファイル作成要求をドライバー スタックに送信します。 アプリケーションまたはドライバーがデバイスの使用を完了すると、システムはファイル クリーンアップとクローズの要求を、ドライバー スタックに送信します。 これら 3 つの要求の要求の種類は、それぞれ WdfRequestTypeCreate、WdfRequestTypeCleanup、WdfRequestTypeClose です。
通常、複数のファイルが同時に開かれたり、複数のアプリケーションが同時にデバイスにアクセスしたりすることがあるため、ドライバーは WdfDeviceInitSetExclusive を呼び出していない限り、ファイルの作成、クリーンアップ、およびクローズ要求を受け取ったら、ファイル固有またはその他のアクセス固有の操作を実行する必要があります。 そのためドライバーは、各ファイルまたはアプリケーションに関連付けられている I/O 要求を追跡する必要があります。
フレームワークは、ファイル、ディレクトリ、ボリューム、メール スロット、名前付きパイプ、デバイス全体など、デバイスにアクセスするためのアプリケーションまたはドライバーの手段を表すフレームワーク ファイル オブジェクトを定義します。 ファイル名はファイル オブジェクトに関連付けることができますが、ファイル名の意味はドライバー固有です。 ファイル名の詳細については、「デバイスの名前空間アクセスの制御」を参照してください。
ドライバーがファイル操作を処理する必要がある場合は、EvtDriverDeviceAdd コールバック関数内から WdfDeviceInitSetFileObjectConfig を呼び出す必要があります。 WdfDeviceInitSetFileObjectConfig メソッドは、WDF_FILEOBJECT_CONFIG 構造体を入力として受け取ります。 ドライバーはこの構造体を使用して、EvtDeviceFileCreate、EvtFileCleanup、EvtFileClose コールバック関数を登録し、必要に応じて、ドライバーがファイル作成要求を受け取るたびにフレームワーク ファイル オブジェクトをフレームワークで作成するかどうかを示します。
ファイル操作を処理するほとんどのドライバーは、フレームワーク ファイル オブジェクトのコンテキスト空間にファイル固有の情報を格納します。 ドライバーがファイル操作を処理するが、ファイル オブジェクトのコンテキスト空間に情報を格納する必要がない場合、フレームワークはドライバー用にフレームワーク ファイル オブジェクトを作成する必要はありません。
ファイルの作成またはオープン
フレームワークがファンクション ドライバーのファイル作成要求を受け取ると、次のように処理します。
ドライバーが以前にフレームワーク ファイル オブジェクトを使用する必要がないことを示していない限り、ファイルを表すフレームワーク ファイル オブジェクトを作成します。
ドライバーが EvtDeviceFileCreate コールバック関数を登録している場合は、このコールバック関数を呼び出します。
EvtDeviceFileCreate コールバック関数は、通常、ファイルに関する情報を取得 (名前やファイル オブジェクト フラグなど) します。 ドライバーは通常、フレームワーク ファイル オブジェクトのコンテキスト空間にこの情報を格納します。
ドライバーは、EvtDeviceFileCreate コールバック関数を提供する代わりに、WdfDeviceConfigureRequestDispatching を呼び出して、すべてのファイル作成要求 (要求の種類 WdfRequestTypeCreate) を受信するように I/O キューを設定できます。 その後ドライバーは、キューの EvtIoDefault 要求ハンドラーでファイル作成要求を受け取ります。 (I/O キューは、キューの WDF_IO_QUEUE_CONFIG 構造体の DefaultQueue メンバーが TRUE に設定されている場合、ファイル作成要求を受信できません。
ドライバーが EvtDeviceFileCreate コールバック関数を提供せず、WdfRequestTypeCreate 型の I/O 要求を処理する I/O キューを設定しない場合、フレームワークは次のように処理します。
ドライバーがファンクション ドライバーの場合は、状態値 STATUS_SUCCESS で、ドライバーのすべてのファイル作成要求を完了します。
ドライバーがフィルター ドライバーの場合は、次の下位ドライバーにすべてのファイル作成要求を転送します。
(この動作を変更する方法については、WDF_FILEOBJECT_CONFIG 構造体の AutoForwardCleanupClose メンバーを参照してください。)
注 ファンクション ドライバーが、アプリケーションがドライバーのデバイスにアクセスするために使用できるデバイス インターフェイスを提供しない場合、ドライバーは、すべてのファイル作成要求を NT_SUCCESS (状態) が FALSE で完了する EvtDeviceFileCreate コールバック関数を提供する必要があります そうしないと、悪意のあるアプリケーションが、デバイスの物理デバイス オブジェクト (PDO) の名前を使用してデバイスへのアクセスを試みる可能性があります。 (すべての PDO には名前があります。)
ドライバーが I/O ターゲットに作成要求を転送する場合、ドライバーは、ドライバーが I/O ターゲットからエラー状態の値を受け取らない限り、後でエラー状態の値で要求を完了してはなりません。 そうしないと、下位のドライバーは作成要求が失敗したことを通知されず、ファイルが開いているかのように動作を試みる可能性があります。
ドライバーが I/O ターゲットに作成要求を転送する場合、フレームワークが作成要求のフレームワーク ファイル オブジェクトを作成した場合、ドライバーはWDF_REQUEST_SEND_OPTION_SEND_AND_FORGET フラグを設定できません。 そのため、スタックの下位のドライバーが作成要求に失敗した場合にドライバーが WDFFILEOBJECT をクリーンアップできないため、WdfFileObjectNotRequired フラグも設定しない限り、ドライバーは作成要求のWDF_REQUEST_SEND_OPTION_SEND_AND_FORGET フラグを設定できません。 代わりに、ドライバーは、他の任意の送信オプションを使用できます。たとえば、完了ルーチンを使用して非同期的に送信したり、同期的に送信したりできます。 どちらの場合も、ドライバーは制御を回復するときに WdfRequestComplete を呼び出す必要があります。
ドライバーがエラー状態で作成要求を完了した場合、フレームワークはフレームワーク ファイル オブジェクトを削除しますが、ドライバーの EvtFileCleanup または EvtFileClose コールバック関数は呼び出しません。 そのため、ドライバーは、ファイル オブジェクトのコンテキスト領域の外部に余分なオブジェクト固有のメモリを割り当てる場合は、割り当てられたメモリを削除する EvtCleanupCallback または EvtDestroyCallback コールバック関数を提供する必要があります。
Windows Vista 以降では、ファイル作成要求を取り消すことができます。 以前のバージョンの Windows オペレーティング システムでは、ファイル作成要求の取り消しはサポートされていません。
システムは、ユーザー アプリケーションから送信される作成要求ごとに、常に Windows ドライバー モデル (WDM) ファイル オブジェクトを作成します。 ドライバーが作成要求を送信する場合は、要求の WDM ファイル オブジェクトを作成しない可能性があります。 通常、WDM ファイル オブジェクトが存在しない場合、フレームワークはフレームワーク ファイル オブジェクトを作成しません。 ただし、ドライバーが WdfDeviceInitSetExclusive を呼び出し、ドライバーが WDF_FILEOBJECT_CONFIG 構造体の FileObjectClass メンバーに WdfFileObjectWdfCannotUseFsContexts を設定している場合、WDM ファイル オブジェクトが存在しない場合でも、フレームワークはフレームワーク ファイル オブジェクトを作成します。
ファイルの情報の取得
ドライバーの EvtDeviceFileCreate コールバック関数は、次の 1 つ以上のオブジェクト メソッドを呼び出して、デバイスへのアプリケーションまたはドライバーのアクセスに関する情報を取得できます。
WdfFileObjectGetFileName
フレームワーク ファイル オブジェクトに含まれているファイル名を返します。
WdfFileObjectGetFlags
フレームワーク ファイル オブジェクト内に含まれるフラグを返します。
WdfFileObjectWdmGetFileObject
フレームワーク ファイル オブジェクトに関連付けられている WDM ファイル オブジェクトを返します。
WdfRequestGetParameters
フレームワーク要求オブジェクトに関連付けられているパラメーターを取得します。 要求の種類が WdfRequestTypeCreate の場合、WDF_REQUEST_PARAMETERS 構造体の Parameters.Create メンバーには、ファイル作成要求に関する情報が含まれます。
ドライバーは通常、フレームワーク ファイル オブジェクトのコンテキスト空間にファイル情報を格納します。 ドライバーは、I/O キューの 1 つから I/O 要求を取得すると、WdfRequestGetFileObject を呼び出して、要求に関連付けられているフレームワーク ファイル オブジェクトへのハンドルを取得できます。 ドライバーは次に、フレームワーク ファイル オブジェクトのコンテキスト空間に格納されているファイル情報を取得できます。
ドライバーは、WdfIoQueueRetrieveRequestByFileObject を呼び出すことによって、特定のファイルに関連付けられている要求の I/O キューを検索できます。
ドライバーに WDM DEVICE_OBJECT 構造体へのポインターがある場合、ドライバーは WdfDeviceGetFileObject を呼び出して、WDM デバイス オブジェクトに関連付けられているフレームワーク ファイル オブジェクトへのハンドルを取得できます。
ファイルを閉じる
アプリケーションまたは別のドライバーがファイルを閉じると、フレームワークはドライバーのクリーンアップ要求とクローズ要求を受け取ります。 フレームワークは次の処理を実行します。
ドライバーの EvtFileCleanup および EvtFileClose コールバック関数を呼び出します (ドライバーがこれらのコールバック関数を登録している場合)。
ファイルを表すフレームワーク ファイル オブジェクトを削除します。
ドライバーの EvtFileCleanup および EvtFileClose コールバック関数は、フレームワーク ファイル オブジェクトへのハンドルを受け取ります。 ドライバーは、WdfFileObjectGetDevice を呼び出して、フレームワーク ファイル オブジェクトに関連付けられているフレームワーク デバイス オブジェクトを決定できます。