WdfIoTargetOpen 関数 (wdfiotarget.h)

[アーティクル]
03/05/2024

[KMDF と UMDF に適用]

WdfIoTargetOpen メソッドは、ドライバーが I/O 要求を送信できるように、リモート I/O ターゲットを開きます。

構文

NTSTATUS WdfIoTargetOpen(
  [in] WDFIOTARGET                IoTarget,
  [in] PWDF_IO_TARGET_OPEN_PARAMS OpenParams
);

パラメーター

[in] IoTarget

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

[in] OpenParams

呼び出し元によって割り当てられた WDF_IO_TARGET_OPEN_PARAMS 構造体へのポインター。

戻り値

操作が成功した場合、WdfIoTargetOpen はSTATUS_SUCCESSを返します。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_DEVICE_STATE	指定した I/O ターゲットは既に開いています。
STATUS_INSUFFICIENT_RESOURCES	使用可能なシステムリソースが、操作を完了するには不十分でした。
STATUS_INFO_LENGTH_MISMATCH	OpenParams が指定したWDF_IO_TARGET_OPEN_PARAMS構造体のサイズが正しくありません。
STATUS_NO_SUCH_DEVICE	呼び出し元の WDF_IO_TARGET_OPEN_PARAMS 構造体の TargetFileObject メンバーが無効なファイルオブジェクトを指定しました。
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_NOT_FOUND	OpenParams パラメーターで識別されるデバイス名が見つかりません。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

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

注釈

ドライバーは、オブジェクト名を表す Unicode 文字列を指定するか、Windows ドライバーモデル (WDM) DEVICE_OBJECT構造体へのポインターを指定することで、リモート I/O ターゲットを開くことができます。 (フレームワークベースのドライバーには、通常、他のドライバーのDEVICE_OBJECT構造体へのポインターがありません)。

WdfIoTargetOpen を呼び出す前にデバイスインターフェイス名を取得するには、UMDF ドライバーは、インターフェイスの到着と削除の通知を登録するCM_Register_Notificationを呼び出す必要があります。その後、インターフェイス通知コールバックルーチンで受け取るインターフェイスシンボリック名を使用して、リモートターゲットを開くことができます。ハンドルが開いている間、ドライバーは引き続き削除通知をリッスンする必要があります。ターゲットドライバーが失敗した場合、UMDF ドライバーはハンドルを閉じる必要があります。

インターフェイスが既に存在する場合、UMDF ドライバーは CM_Get_Device_Interface_Listを呼び出す必要があります。必要なバッファーサイズを決定するために、最初に CM_Get_Device_Interface_List_Size を呼び出す可能性があります。

ドライバーでローカル I/O ターゲットを使用する場合、ドライバーは WdfIoTargetOpen ではなく WdfDeviceGetIoTarget を呼び出す必要があります。

WdfIoTargetOpen の呼び出しが失敗した場合、ドライバーは WdfObjectDelete を呼び出して I/O ターゲットオブジェクトを削除する必要があります。

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

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

例

次の例では、I/O ターゲットオブジェクトを作成し、 WDF_IO_TARGET_OPEN_PARAMS 構造体を初期化し、デバイスのシンボリックリンク名を指定してリモート I/O ターゲットを開きます。

WDF_OBJECT_ATTRIBUTES  ioTargetAttrib;
WDFIOTARGET  ioTarget;
WDF_IO_TARGET_OPEN_PARAMS  openParams;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &ioTargetAttrib,
                                        TARGET_DEVICE_INFO
                                        );
status = WdfIoTargetCreate(
                           device,
                           &ioTargetAttrib,
                           &ioTarget
                           );
if (!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME(
                                            &openParams,
                                            SymbolicLink,
                                            STANDARD_RIGHTS_ALL
                                            );
status = WdfIoTargetOpen(
                         ioTarget,
                         &openParams
                         );
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(ioTarget);
    return status;
}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	wdfiotarget.h (Wdf.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)