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

UMDF の場合、WdfIoTargetWdmGetTargetFileHandle は、現在のプロセスでのみ有効な Win32 HANDLE を返します。 レガシ UMDF ドライバー (バージョン 1.x) は、IWDFDevice::RetrieveDeviceName を呼び出して、基になるカーネル モード デバイスの名前を取得し、CreateFileでハンドルを開きます。 ドライバーは、DeviceIoControlを使用して、下位デバイスに直接 I/O を送信できます。 UMDF 2.15 以降、UMDF v2 ドライバーは、ローカル I/O ターゲットをファイル (WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE) で開き、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
ヘッダー	wdfiotarget.h (Wdf.h を含む)
図書館	Wdf01000.sys (フレームワーク ライブラリのバージョン管理を参照)。
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則 を する	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

こちらもご覧ください

WdfIoTargetCreate の

WdfIoTargetWdmGetTargetFileObject