次の方法で共有

フレームワーク ファイル オブジェクト

  • [アーティクル]

アプリケーションまたはドライバーが、デバイスへのアクセス (通常はファイルを作成するまたは開く操作) を試みると、オペレーティング システムがドライバー スタックにファイル作成要求を送信します。アプリケーションまたはドライバーがデバイスを使い終わると、ファイルのクリーンアップ要求と終了要求がドライバー スタックに送信されます。これら 3 つの要求の種類は、それぞれ WdfRequestTypeCreate、WdfRequestTypeCleanup、および WdfRequestTypeClose です。

ドライバーが WdfDeviceInitSetExclusive を呼び出していない場合、複数のファイルを同時に開くことや、複数のアプリケーションから同時にデバイスにアクセスすることができるため、ドライバーは、ファイルの作成、クリーンアップ、および終了要求を受信すると、通常はファイル別、またはアクセス別に操作を実行する必要があります。このため、ドライバーは、各ファイルまたはアプリケーションに関連付けられた I/O 要求を記録しておく必要があります。

フレームワークでは、"フレームワーク ファイル オブジェクト" が定義されています。このオブジェクトは、アプリケーションまたはドライバーがデバイスにアクセスするための方法 (ファイル、ディレクトリ、ボリューム、メール スロット、名前付きパイプ、またはデバイス全体) を表します。ファイル名をファイル オブジェクトに関連付けることはできますが、ファイル名の意味はドライバーによって異なります。ファイル名の詳細については、「デバイスの名前空間へのアクセスの制御」(英語の可能性あり) を参照してください。

ドライバーでファイル操作を処理する必要がある場合は、ドライバーの EvtDriverDeviceAdd コールバック関数から WdfDeviceInitSetFileObjectConfig を呼び出す必要があります。WdfDeviceInitSetFileObjectConfig メソッドは、WDF_FILEOBJECT_CONFIG 構造体を入力として受け取ります。ドライバーは、この構造体を使用して、EvtDeviceFileCreate、EvtFileCleanup、および EvtFileClose の各コールバック関数を登録し、必要に応じて、ドライバーがファイル作成要求を受信するたびにフレームワークがフレームワーク ファイル オブジェクトを作成する必要があるかどうかを指定します。

ファイル操作を処理する多くのドライバーは、フレームワーク ファイル オブジェクトのコンテキスト領域に、ファイル固有の情報を保存します。ドライバーでファイル操作を処理するが、ファイル オブジェクトのコンテキスト領域に情報を保存する必要がない場合、フレームワークはそのドライバーに対してフレームワーク ファイル オブジェクトを作成する必要はありません。

ファイルの作成またはオープン

フレームワークは、関数ドライバーに対するファイル作成要求を受信すると、次の処理を行います。

  1. フレームワーク ファイル オブジェクトを使用する必要がないことがドライバーから事前に指定されていなければ、そのファイルを表すフレームワーク ファイル オブジェクトを作成します。

  2. ドライバーが 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 フラグを設定できません。このため、ドライバーは、WdfFileObjectNotRequired フラグを設定していない限り、作成要求の WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET フラグを設定できません。

ドライバーがエラー状態の作成要求を完了させた場合、フレームワークはフレームワーク ファイル オブジェクトを削除しますが、ドライバーの EvtFileCleanup コールバック関数または EvtFileClose コールバック関数を呼び出しません。このため、ドライバーがファイル オブジェクトのコンテキスト領域以外の場所にオブジェクト固有の追加メモリを割り当てる場合は、割り当てたメモリを削除する EvtCleanupCallback コールバック関数または EvtDestroyCallback コールバック関数を提供する必要があります。

Windows Vista 以降では、ファイル作成要求を取り消すことができます。これより前のバージョンの Windows オペレーティング システムでは、ファイル作成要求の取り消しはサポートされていません。

ユーザー アプリケーションから作成要求が送信されると、各要求について必ず Windows Driver Model (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 キューから I/O 要求を受け取ると、WdfRequestGetFileObject を呼び出して、その要求に関連付けられたフレームワーク ファイル オブジェクトのハンドルを取得できます。これにより、ドライバーは、フレームワーク ファイル オブジェクトのコンテキスト領域に格納したファイル情報を取得できるようになります。

また、WdfIoQueueRetrieveRequestByFileObject を呼び出して、特定のファイルに関連付けられた要求を I/O キュー内で検索することができます。

WDM DEVICE_OBJECT 構造体へのポインターを保持している場合は、ドライバーから WdfDeviceGetFileObject を呼び出して、WDM デバイス オブジェクトに関連付けられたフレームワーク ファイル オブジェクトのハンドルを取得できます。

ファイルの終了

アプリケーションまたは他のドライバーがファイルを閉じると、フレームワークはドライバーに対するクリーンアップ要求と終了要求を受信します。フレームワークは次の処理を行います。

  1. ドライバーが EvtFileCleanup と EvtFileClose の各コールバック関数を提供している場合は、これらのコールバック関数を呼び出します。

  2. 対象のファイルを表すフレームワーク ファイル オブジェクトを削除します。

ドライバーの EvtFileCleanup と EvtFileClose の各コールバック関数は、フレームワーク ファイル オブジェクトへのハンドルを受け取ります。ドライバーは、WdfFileObjectGetDevice を呼び出して、対象のフレームワーク ファイル オブジェクトに関連付けられたフレームワーク デバイス オブジェクトを特定できます。