DIF_INSTALLDEVICE

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

DIF_INSTALLDEVICE 要求を使用すると、インストーラーはデバイスのインストール前またはインストール後にタスクを実行できます。

送信時

ドライバーを選んだ後、任意のデバイス共同インストーラーを登録し、デバイスインターフェイスを登録します。

処理するユーザー

クラス共同インストーラー	処理できる
デバイス共同インストーラー	処理できる
クラスインストーラー	処理できる

インストーラーによる入力

DeviceInfoSet
デバイスを格納しているデバイス情報セットへの処理を提供します。

DeviceInfoData
デバイス情報セット内のデバイスの SP_DEVINFO_DATA 構造体へのポインターが提供されます。

デバイスインストールパラメーター
DeviceInfoData に関連付けられているデバイスインストールパラメーター (SP_DEVINSTALL_PARAMS) があります。

クラスインストールパラメーター
なし

インストーラーによる出力

デバイスインストールパラメーター
インストーラーは、DeviceInfoData のデバイスインストールパラメーターを変更できます。たとえば、インストーラーで DI_NEEDREBOOT フラグを設定したり、DI_DONOTCALLCONFIGMG フラグを設定して、新しくインストールされたドライバーと設定を使用して Windows がデバイスを動的にオンラインにできないようにしたりできます。

インストーラーの戻り値

共同インストーラーは通常、NO_ERROR または ERROR_DI_POSTPROCESSING_REQUIRED を返します。共同インストーラーから [Win32] エラーコードが返される場合もあります。

クラスインストーラーがこの要求を正常に処理し、その後 SetupDiCallClassInstaller が既定のハンドラーを呼び出す必要がある場合、クラスインストーラーは ERROR_DI_DO_DEFAULT を返します。

既定のハンドラーの直接呼び出しを含め、クラスインストーラーがこの要求を正常に処理した場合、クラスインストーラーは NO_ERROR を返す必要があり、その後 SetupDiCallClassInstaller は既定のハンドラーをもう一度呼び出しません。

注: クラスインストーラーは既定のハンドラーを直接呼び出すことができますが、クラスインストーラーは既定のハンドラーの操作を置き換えようとしないでください。既定の DIF コードハンドラーの呼び出しの詳細については、「既定の DIF コードハンドラーの呼び出し」を参照してください。

クラスインストーラーでエラーが見つかった場合、インストーラーは適切な Win32 エラーコードを返す必要があり、SetupDiCallClassInstaller は既定のハンドラーを呼び出しません。

既定の DIF コードハンドラー

SetupDiInstallDevice

インストーラー操作

DIF_INSTALLDEVICE 要求に応じて、インストーラーは通常、既定のハンドラーがデバイスをインストールする前に、最終的なインストール操作を実行します。たとえば、インストーラーは、レジストリに一覧表示されているデバイスの上位フィルタードライバーと下位フィルタードライバーをチェックしたり、変更したりすることができます。

DI_NOFILECOPY フラグがデバイスのインストールパラメーターに設定されていない限り、この DIF 要求を処理するインストーラーは、ドライバーファイルやコントロールパネルファイルなど、デバイスに必要なファイルをコピーする必要があります。

DI_NOFILECOPY フラグがクリアされていても、DI_NOVCP フラグが設定されている場合、インストーラーは指定されたファイルキューにファイル操作をエンキューする必要がありますが、キューをコミットすることはできません。

共同インストーラーは、前処理パスまたは後処理パスで、この DIF 要求を処理できます。その前処理パスでは、共同インストーラーは、Windows がドライバーを読み込んでデバイスを起動する前に行わなければならない操作を実行します。

後処理パスでは、DI_NEEDREBOOT フラグが設定されていない限り、デバイスは稼働しています。このフラグが設定されている場合、Windows はデバイスを動的にオンラインにできませんでした。

インストーラーから Win32 エラーコードが返された場合、Windows はインストールを中止します。

Windows は、新しいデバイスの INF ファイルを見つけることができない場合は、null ドライバーをインストールしようとして DIF_INSTALLDEVICE を送信します。既定のハンドラー (SetupDiInstallDevice) は、デバイスが未加工モードをサポートしているか、PnP 以外のデバイス (IoReportDetectedDevice による報告) であるかをチェックします。後者の場合、Windows はデバイスの null ドライバーをインストールします。

この試行が失敗した場合、Windows はもう一度 DIF_INSTALLDEVICE を送信し、今度は SP_DEVINSTALL_PARAMS 構造体に DI_FLAGSEX_SETFAILEDINSTALL フラグを設定します。この場合、既定のハンドラーは、デバイスの ConfigFlags レジストリ値に FAILEDINSTALL フラグを設定するだけです。 DI_FLAGSEX_SETFAILEDINSTALL フラグが設定されている場合、クラスインストーラーは NO_ERROR または ERROR_DI_DO_DEFAULT を返す必要があり、共同インストーラーは NO_ERROR を返す必要があります。

DIF コードの詳細については、「DIF コードの処理」を参照してください。

既定のハンドラー SetupDiInstallDevice の呼び出し

SetupDiInstallDevice を呼び出すタイミングと方法の一般的な情報については、「既定の DIF コードハンドラーの呼び出し」を参照してください。

デバイスの起動を除くすべての SetupDiInstallDevice 操作が完了した後、クラスインストーラーが操作を実行する必要があるまれな状況では、クラスインストーラーは次の操作を実行する必要があります。

SetupDiInstallDevice を呼び出す前に実行する必要がある操作を実行します。
SP_DEVINSTALL_PARAMS で DI_DONOTCALLCONFIGMGR フラグを設定します。デバイスのフラグ メンバー。このフラグが設定されている場合、SetupDiInstallDevice は、デバイスの起動を除くすべての既定のインストール操作を実行します。
SetupDiInstallDevice を呼び出して、デバイスの起動を除くすべての既定のインストール操作を実行します。
デバイスの起動を除くすべての既定のインストール操作が完了した後に実行する必要がある操作を実行します。
SetupDiRestartDevices を呼び出してデバイスを起動します。
クラスインストーラーが正常にインストール操作を完了した場合は NO_ERROR を返し、インストール操作が失敗した場合は Win32 エラーを返します。

要件

バージョン	Microsoft Windows 2000 以降のバージョンの Windows でサポートされています。
ヘッダー	Setupapi.h (Setupapi.h を含む)