DiInstallDevice 関数 (newdev.h)

[アーティクル]
03/08/2023

DiInstallDevice 関数は、システムに存在する指定したデバイスのドライバーストアにプレインストールされている指定されたドライバーをインストールします。

構文

BOOL DiInstallDevice(
  [in, optional]  HWND             hwndParent,
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in, optional]  PSP_DRVINFO_DATA DriverInfoData,
  [in]            DWORD            Flags,
  [out, optional] PBOOL            NeedReboot
);

パラメーター

[in, optional] hwndParent

DiInstallDevice がデバイスのインストールに関連付けられているユーザーインターフェイスコンポーネントを表示するために使用する最上位ウィンドウへのハンドル。このパラメーターは省略可能であり、 NULL に設定できます。

[in] DeviceInfoSet

指定したデバイスを表すデバイス情報要素を含むデバイス情報セットへのハンドル。

[in] DeviceInfoData

指定したデバイス情報セット内の指定したデバイスを表す SP_DEVINFO_DATA 構造体へのポインター。

[in, optional] DriverInfoData

指定したデバイスにインストールするドライバーを指定する SP_DRVINFO_DATA 構造体へのポインター。このパラメーターは省略可能であり、 NULL に設定できます。このパラメーターが NULL の場合、 DiInstallDevice は、ドライバーストアにプレインストールされているドライバーで、指定したデバイスに最も一致するドライバーを検索し、見つかった場合は、指定したデバイスにドライバーをインストールします。

[in] Flags

0 または次のフラグを指定する DWORD 型の値。

DIIDFLAG_SHOWSEARCHUI

呼び出し元がドライバーを指定せず (DriverInfoData が NULL に設定されている) 場合、 DiInstallDevice は、指定されたデバイスと一致するプレインストールドライバーを見つけることができません。代わりに、 DiInstallDevice に デバイスの [新しいハードウェアが見つかりました] ウィザードが表示されます。

DIIDFLAG_NOFINISHINSTALLUI

DiInstallDevice は、ウィザードページの完了とインストールの完了操作を開始しません。 DiInstallDevice の呼び出し元は、これらの操作を開始する必要があります。呼び出し元は、呼び出し元が呼び出し元から提供されたユーザーインターフェイスコンポーネントのコンテキストで完了インストールウィザードページを呼び出す必要がある場合にのみ、このフラグを指定する必要があります。

DIIDFLAG_INSTALLNULLDRIVER

DiInstallDevice は、指定されたデバイスに null ドライバーをインストールしようとします。このフラグが設定されている場合、 DiInstallDevice は DriverInfoData パラメーターを使用しません。 DiInstallDevice はすべての デバイス設定を削除し、デバイスを未加工モードで実行できない場合、関数はデバイスの状態を CM_PROB_FAILED_INSTALLに設定します。 DiInstallDevice が null ドライバーをインストールできない場合、デバイスの結果の状態は、デバイスがコンピューターに初めて接続され、Windows がデバイスのドライバーを見つけられなかった場合と同じです。

DIIDFLAG_INSTALLCOPYINFDRIVERS

CopyINF ディレクティブを使用して指定された追加の INF ファイルは、適用可能な任意のデバイスにインストールされます。追加の INF のインストールでエラーが発生しても、プライマリ INF のインストールが失敗することはありません。

[out, optional] NeedReboot

インストールを完了するためにシステムの再起動が必要かどうかを示すために DiInstallDevice が設定する BOOL 型の値へのポインター。このパラメーターは省略可能であり、 NULL に設定できます。このパラメーターを指定し、インストールを完了するためにシステムの再起動が必要な場合、 DiInstallDevice は値を TRUE に設定します。この場合、呼び出し元はシステムの再起動を担当します。このパラメーターを指定し、システムの再起動が不要な場合、 DiInstallDevice はこのパラメーターを FALSE に設定 します。このパラメーターが NULL で、インストールを完了するためにシステムの再起動が必要な場合、 DiInstallDevice はシステムの再起動ダイアログボックスを表示します。

戻り値

関数が指定したデバイスに指定したドライバーを正常にインストールした場合、DiInstallDevice は TRUE を返します。それ以外の場合、 DiInstallDevice は FALSE を 返し、 GetLastError を呼び出すことでログに記録されたエラーを取得できます。 GetLastError が返す可能性がある一般的なエラー値の一部は次のとおりです。

リターンコード	説明
ERROR_ACCESS_DENIED	呼び出し元には管理者特権がありません。既定では、Windows Vista と Windows Server 2008 では、呼び出し元のプロセスにデバイスにドライバーをインストールするための管理者特権が必要です。
ERROR_INVALID_FLAGS	Flags に指定された値は、有効なフラグの 0 またはビットごとの OR ではありません。
ERROR_IN_WOW64	呼び出し元のアプリケーションは、64 ビット環境で実行しようとしている 32 ビットアプリケーションです。これは許可されていません。詳細については、「 64 ビットシステムへのデバイスのインストール」を参照してください。

注釈

特定のデバイスに特定のドライバーをインストールする必要がある場合にのみ 、DiInstallDevice を呼び出します。それ以外の場合は、 UpdateDriverForPlugAndPlayDevices または DiInstallDriver を使用して、デバイスのドライバーをインストールします。デバイスにドライバーをインストールするために呼び出すこれらの関数の詳細については、「ドライバーのインストールを簡略化する SetupAPI Functions」を参照してください。

DiInstallDevice を呼び出す前に、呼び出し元はSP_DEVINFO_DATA構造体を取得してデバイスを指定し、必要に応じて、デバイスのドライバーを指定するSP_DRVINFO_DATA構造体を取得する必要があります。

指定したデバイスを含むデバイス情報セットを作成し、デバイスの SP_DEVINFO_DATA 構造を取得するには、次のいずれかの操作を行います。

SetupDiGetClassDevs を呼び出してデバイスを含むデバイス情報セットを取得し、SetupDiEnumDeviceInfo を呼び出してデバイス情報セット内のデバイスを列挙します。各呼び出しで、 SetupDiEnumDeviceInfo は、デバイス情報セット内の列挙されたデバイスを表す SP_DEVINFO_DATA 構造体を返します。列挙されたデバイスに関する特定の情報を取得するには、SetupDiGetDeviceProperty を呼び出し、SetupDiEnumDeviceInfo によって返されるSP_DEVINFO_DATA構造体を指定します。
- または -
SetupDiOpenDeviceInfo を呼び出して、既知のデバイスインスタンス ID を持つデバイスをデバイス情報セットに追加します。 SetupDiOpenDeviceInfo は、デバイス情報セット内のデバイスを表す SP_DEVINFO_DATA 構造体を返します。

選択したドライバーのSP_DRVINFO_DATA 構造を取得するには、 SetupDiBuildDriverInfoList を呼び出してデバイスのドライバーの一覧を作成し、 SetupDiEnumDriverInfo を呼び出してデバイスのドライバーリストの要素を列挙します。列挙されたドライバーごとに、 SetupDiEnumDriverInfo はドライバーを識別する SP_DRVINFO_DATA 構造体を取得します。 SetupDiGetDriverInfoDetail を呼び出して、列挙ドライバーに関する追加の詳細を取得することもできます。

一般に、インストールアプリケーションで NeedReboot を NULL に設定する必要があります。これにより、インストールを完了するために再起動が必要な場合に、 DiInstallDevice がユーザーにシステムの再起動を求められます。アプリケーションでは、次の場合にのみ NeedReboot ポインターを指定する必要があります。

インストールを完了するには、アプリケーション で DiInstallDevice を複数回呼び出す必要があります。この場合、アプリケーションは、DiInstallDevice の呼び出しによって TRUENeedReboot 値が返されるかどうかを記録し、その場合は、DiInstallDevice の最後の呼び出しが返された後にシステムを再起動するようにユーザーに求める必要があります。
アプリケーションは、システムの再起動を行う前に、 DiInstallDevice を呼び出す以外の必要な操作を実行する必要があります。システムの再起動が必要な場合、アプリケーションは必要な操作を完了し、ユーザーにシステムの再起動を求めるメッセージを表示する必要があります。
アプリケーションはクラスインストーラーです。その場合、クラスインストーラーは、デバイスの SP_DEVINSTALL_PARAMS 構造体の Flags メンバーに DI_NEEDREBOOT フラグを設定する必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows Vista 以降のバージョンの Windows で使用できます。
対象プラットフォーム	デスクトップ
Header	newdev.h (Newdev.h を含む)
Library	Newdev.lib
[DLL]	Newdev.dll