WdfIoTargetWdmGetTargetFileHandle 関数 (wdfiotarget.h)

[アーティクル]
02/27/2024

[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

次の方法で共有

WdfIoTargetWdmGetTargetFileHandle 関数 (wdfiotarget.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

その他のリソース