DIF_SELECTDEVICE

[アーティクル]
06/15/2023

DIF_SELECTDEVICE 要求を使用すると、インストーラーはデバイスのドライバーの選択に参加できます。

送信時

新しく列挙されたデバイスのドライバを選択する場合、または既存のデバイスの新しいドライバを選択する場合（ドライバーの変更）。たとえば、ユーザーが [ハードウェアの追加/削除] を選び、モデムクラスを選ぶとします。または、ユーザーが PnP デバイスを挿入し、検出された新しいハードウェアウィザードで [一覧からドライバーを選択] を選びます。

処理するユーザー

クラス共同インストーラー	処理できる
デバイス共同インストーラー	取り扱いなし
クラスインストーラー	処理できる

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

DeviceInfoSet
ドライバを選択するデバイスを含むデバイス情報セットへのハンドルを提供します。 DeviceInfoSet に関連付けられているデバイスセットアップクラスがあります。

DeviceInfoData
デバイスの情報セット内でデバイスを識別する SP_DEVINFO_DATA 構造体へのポインターを必要に応じて提供します。

DeviceInfoData が NULL の場合、この要求は DeviceInfoSet に関連付けられているデバイスセットアップクラスのドライバーを選ぶことです。

デバイスインストールパラメーター
DeviceInfoData が NULL でない場合は、DeviceInfoData に関連付けられているデバイスインストールパラメーター (SP_DEVINSTALL_PARAMS) があります。 DeviceInfoData が NULL の場合、DeviceInfoSetに関連付けられているデバイスインストールパラメーターがあります。

特に重要なのは DriverPath です。DriverPath には、ドライバーの一覧を作成するときに使用する INF の場所が含まれています。

クラスインストールパラメーター
DeviceInfoData が NULL でない場合、SP_SELECTDEVICE_PARAMS構造体は DeviceInfoData に関連付けられます。それ以外の場合、クラスインストールパラメーターは、デバイス情報セット全体に関連付けられます。

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

デバイスインストールパラメーター
インストーラーによってデバイスインストールパラメーターが変更される場合があります。ただし、DriverPath フィールドは変更してはいけません。

クラスインストールパラメーター
インストーラーは、SP_SELECTDEVICE_PARAMS を変更できます。たとえば、インストーラーでは、ユーザーにドライバーの選択を求めるダイアログボックスで Windows で使用するタイトルや手順を指定できます。

インストーラーで新しいドライバー選択パラメーターを設定する場合と、以前のインストーラーによって設定されたパラメーターを変更する場合は、インストーラーが設定していないフィールドをゼロにする必要があります。

インストーラーの戻り値

共同インストーラーがこの DIF コードに対して何も行わない場合、前処理パスから NO_ERROR を返します。共同インストーラーがこの DIF コードを処理する場合は、その前処理パスでこれを行い、NO_ERRORまたは Win32 エラーコードを返す必要があります。後処理のために共同インストーラーが呼び出されるまでに、ドライバーは既に選ばれています。

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

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

注: クラスインストーラーは既定のハンドラーを直接呼び出すことができますが、クラスインストーラーは既定のハンドラーの操作を置き換えようとしないでください。

既定のハンドラーの呼び出しの詳細については、「既定の DIF コードハンドラーの呼び出し」を参照してください。

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

クラスインストーラーは、対応するSP_DEVINSTALL_PARAMS 構造体の DriverPathメンバーが NULL と等しくないが、指定したパスの場所に有効なドライバーがない場合に、ERROR_DI_BAD_PATH を返します。これは、パスの場所にドライバーがない場合、またはドライバーがあるが、各ドライバーの SP_DRVINSTALL_PARAMS 構造体の フラグ メンバーが DN_BAD_DRIVER フラグで設定されている場合に発生する可能性があります。このエラーコードに応答して、Windows はユーザーにエラーを表示します。

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

SetupDiSelectDevice

インストーラー操作

DIF_SELECTDEVICE 要求に応答して、インストーラーは、既定のハンドラーの動作以外に、そのデバイスまたはデバイスクラスに必要なすべての選択操作を実行します。インストーラーは通常、次のいずれかの方法でこの DIF 要求に応答します。

何もしない。

インストーラーに特別な選択要件がない場合、この DIF コードに応答しても何も行われません。クラスインストーラーは ERROR_DI_DO_DEFAULT を返し、共同インストーラーは NO_ERROR を返します。
Windows が選択 UI に表示する選択文字列を指定します。

インストーラーは、クラスインストールパラメーター (SP_SELECTDEVICE_PARAMS) で選択文字列を指定できます。たとえば、インストーラーは、仕様書 またはウィンドウヘッダー タイトル を変更できます。

共同インストーラーで既に選択文字列が指定されている場合、クラスインストーラーは選択文字列を指定しないでください。共同インストーラーには、より関連性の高い情報が含まれている可能性があります。

インストーラーが SP_SELECTDEVICE_PARAMS を変更する場合、インストーラーは SP_DEVINSTALL_PARAMS で DI_USECI_SELECTSTRINGS フラグも設定する必要があります。

インストーラーが選択文字列を正常に指定した場合でも、Windows は既定のハンドラーを呼び出す必要があります。したがって、この場合、共同インストーラーは NO_ERROR を返し、クラスインストーラーは ERROR_DI_DO_DEFAULT を返します。
デバイスのインストールパラメーターを変更します。

インストーラーは、デバイスのインストールパラメーター (SP_DEVINSTALL_PARAMS) を変更できます。たとえば、インストーラーで DI_SHOWOEM フラグを設定して、Windows に [ディスクを持つ] ボタンを表示させる場合があります。

クラスインストーラーがデバイスのインストールパラメーターを正常に変更すると、クラスインストーラーは ERROR_DI_DO_DEFAULT を返します。
ユーザーが選択できるドライバーの一覧を変更します。

このアクションはあまり一般的ではありませんが、可能です。ドライバーの一覧を変更するインストーラーは、選択文字列も提供する可能性がありますし、提供しないない場合もあります。

通常、ドライバーの一覧を変更するインストーラーは、デバイスに不適切なドライバーをマークします。インストーラーは、このようなドライバーをフラグ DNF_BAD_DRIVER でマークします。 Windows では、ユーザーに表示される一覧からこれらのドライバーが省略されます。

インストーラーは、次の手順に従って、不適切なドライバーをマークします。
1. ドライバーの一覧をビルドするには、SPDIT_CLASSDRIVER のDriverType を使用して SetupDiBuildDriverInfoList を呼び出します。
2. SetupDiEnumDriverInfo と SetupDiGetDriverInstallParams を呼び出すことで、一覧の最初のドライバーに関する情報を取得します。ドライバーがデバイスに適していない場合は、パラメーターの フラグ フィールドに DNF_BAD_DRIVER フラグを設定します。 SetupDiSetDriverInstallParams を呼び出して、パラメーターに変更を適用します。
3. リスト内のすべてのドライバーを処理するまで、前の手順を繰り返します。その関数の参照ページで説明されているように、MemberIndex パラメーターを SetupDiEnumDriverInfo にインクリメントしてください。
インストーラーは、ドライバー一覧の 1 つ以上のドライバーの DNF_BAD_DRIVER フラグを設定する場合がありますが、インストーラーは、そのフラグをクリアしてはいけません。

1 つ以上のインストーラーがドライバー一覧を正常に変更した場合でも、Windows は既定のハンドラーを呼び出す必要があります。したがって、この場合、共同インストーラーは NO_ERROR を返し、クラスインストーラーは ERROR_DI_DO_DEFAULT を返します。
独自のドライバー選択ユーザーインターフェイスを表示し、選択したドライバーを設定します。

クラスインストーラーのみが、独自のドライバー選択ユーザーインターフェイスを表示できます。共同インストーラーは使用できません。たとえば、クラスインストーラーでは、テキストリストの代わりに画像が表示される場合があります。

クラスインストーラーが選択したドライバーを正常に設定した場合、クラスインストーラーは NO_ERROR を返し、Windows は既定のハンドラーを呼び出さないため、既定の選択インターフェイスは表示されません。

DI_ENUMSINGLEINF フラグがデバイスのインストールパラメーターに設定されている場合、DriverPath はディレクトリのパスの代わりに、1 つの INF ファイルのパスです。インストーラーでは、ドライバーの一覧をビルドするために、その 1 つの INF のみを使用する必要があります。

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

要件

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

次の方法で共有