WdfIoTargetWdmGetTargetFileHandle 関数 (wdfiotarget.h)

[KMDF と UMDF に適用]

WdfIoTargetWdmGetTargetFileHandle メソッドは、指定されたリモート I/O ターゲットに関連付けられているファイルへのハンドルを返します。

構文

HANDLE WdfIoTargetWdmGetTargetFileHandle(
  [in] WDFIOTARGET IoTarget
);

パラメーター

[in] IoTarget

リモート I/O ターゲット オブジェクトへのハンドル。 このハンドルは、 WdfIoTargetCreate の以前の呼び出しから取得されました。

戻り値

ドライバーが WdfIoTargetOpen を呼び出したときにオブジェクト名を指定した場合、 WdfIoTargetWdmGetTargetFileHandle は、指定された I/O ターゲットに関連付けられているファイル ハンドルを返します。 それ以外の場合 、WdfIoTargetWdmGetTargetFileHandle は NULL を返します。

ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。

注釈

KMDF の場合、返されるファイル ハンドルは、任意のスレッド コンテキストで有効なカーネル モード ハンドルです。 ドライバーがこのファイル ハンドルを使用する方法については、「 ファイル ハンドルの使用」を参照してください。

WdfIoTargetWdmGetTargetFileHandle メソッドが返すファイル ハンドルは、ドライバーが WdfIoTargetClose または WdfIoTargetCloseForQueryRemove を呼び出すか、リモート I/O ターゲット オブジェクトが削除されるまで有効です。 ドライバーがリモート I/O ターゲット オブジェクトの EvtCleanupCallback 関数を提供し、リモート I/O ターゲットを閉じる前にオブジェクトが削除された場合、 ポインターは EvtCleanupCallback 関数が返されるまで有効です。

ドライバーが削除された後に WDM デバイス オブジェクトにアクセスしようとすると、ドライバーによってシステムがクラッシュする可能性があります。 トーストモン サンプルは、ドライバーが EvtIoTargetQueryRemove コールバック関数を提供して、I/O ターゲットが削除された場合に通知されるようにする方法を示しています。

UMDF の場合、 WdfIoTargetWdmGetTargetFileHandle は、現在のプロセスでのみ有効な Win32 HANDLE を返します。 レガシ UMDF ドライバー (バージョン 1。x) は IWDFDevice::RetrieveDeviceName を呼び出して、基になるカーネル モード デバイスの名前を取得し、 CreateFile でハンドルを開きます。 その後、ドライバーは DeviceIoControl を使用して下位デバイスに直接 I/O を送信できます。 UMDF 2.15 以降、UMDF v2 ドライバーは、ファイル (WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE) によってローカル I/O ターゲットを開き、 WdfIoTargetWdmGetTargetFileHandle を使用してファイル ハンドルを取得できます。 フレームワークは、リモート ターゲットが閉じられたり削除されたりしたときに、ファイル ハンドルを開いたり閉じたりします。 ファイル ハンドルは、前述の WdfIoTargetWdmGetTargetFileHandle のコントラクト内で有効なままです。

警告

UMDF v2 ドライバーが WdfIoTargetWdmGetTargetFileHandle を呼び出して、WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILEを使用して開かれたリモート ターゲットから Win32 ハンドルを取得する場合は、 DeviceIoControl などの API で重複/非同期 I/O を送信しないでください。 これにより、ドライバーをホストしているプロセスがクラッシュする可能性があります。 ドライバーが重複する I/O を送信する必要がある場合は、OVERLAPPED 構造体の hEvent メンバーの下位ビットも設定する必要があります。 これは、フレームワークが内部的にハンドルを I/O 完了ポートにバインドするためです。 下位ビットが設定されている有効なイベント ハンドルは、I/O 完了がキューに登録されてから完了ポートに保持されます。

WdfIoTargetWdmGetTargetFileHandle の詳細については、「一般的な I/O ターゲットに関する情報の取得」を参照してください。

I/O ターゲットの詳細については、「I /O ターゲットの使用」を参照してください。

例

次のコード例では、指定したリモート I/O ターゲットに関連付けられているファイルへのハンドルを取得します。

HANDLE h;

h = WdfIoTargetWdmGetTargetFileHandle(IoTarget);

レガシ UMDF ドライバー (バージョン 1。x) は IWDFDevice::RetrieveDeviceName を呼び出して、基になるカーネル モード デバイスの名前を取得し、 CreateFile でハンドルを開きます。 その後、ドライバーは DeviceIoControl を使用してデバイスに直接 I/O を送信します。

UMDF 2.15 以降、ドライバーはローカル I/O ターゲットをファイル別に開き、そのハンドルを取得します。 フレームワークは、ファイル ハンドルを開いて閉じます。 ファイル ハンドルは、 WdfIoTargetWdmGetTargetFileHandle のコントラクト内で有効なままです。

NTSTATUS status;

WDF_IO_TARGET_OPEN_PARAMS params;

WDFIOTARGET ioTarget = NULL;

HANDLE handle = NULL;

status = WdfIoTargetCreate(Device, &attr, &ioTarget);

if (!NT_SUCCESS(status)) {

    // error handling

}

WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE(&params, NULL);

status = WdfIoTargetOpen(ioTarget, &params);

if (!NT_SUCCESS(status)) {

    // error handling

}

handle = WdfIoTargetWdmGetTargetFileHandle(ioTarget);

if (handle == NULL) {

    // error handling

}

if (ioTarget != NULL) {
    WdfIoTargetClose(ioTarget);
}
// You can now call DeviceIoControl(handle, ...) etc.
// NOTE: See Warning above on submitting overlapped or asynchronous I/O

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.15
Header	wdfiotarget.h (Wdf.h を含む)
Library	Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

こちらもご覧ください

WdfIoTargetCreate

WdfIoTargetWdmGetTargetFileObject