UpdateDriverForPlugAndPlayDevicesW 関数 (newdev.h)

  • [アーティクル]

INF ファイルと ハードウェア ID を指定すると、 UpdateDriverForPlugAndPlayDevices 関数は、ハードウェア ID に一致するデバイスの更新されたドライバーをインストールします。

構文

BOOL UpdateDriverForPlugAndPlayDevicesW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR HardwareId,
  [in]            LPCWSTR FullInfPath,
  [in]            DWORD   InstallFlags,
  [out, optional] PBOOL   bRebootRequired
);

パラメーター

[in, optional] hwndParent

デバイスのインストールに関連するすべての UI に使用する最上位ウィンドウへのハンドル。

[in] HardwareId

コンピューター上の既存のデバイスと一致するハードウェア識別子を提供する NULL で終わる文字列へのポインター。 NULL で終了するハードウェア識別子の最大長はMAX_DEVICE_ID_LEN。 ハードウェア識別子の詳細については、「 デバイス識別文字列」を参照してください。

[in] FullInfPath

INF ファイルの完全なパス ファイル名を提供する NULL で終わる文字列へのポインター。 ファイルは、 %SystemRoot%\inf などのシステムの場所ではなく、配布メディアまたはベンダーが作成したディレクトリに配置する必要があります。 インストールが成功した場合、UpdateDriverForPlugAndPlayDevices はドライバー ファイルを適切なシステムの場所にコピーします。

[in] InstallFlags

OR を使用して次のビット フラグを 0 個以上組み合わせて作成された呼び出し元から指定された値。

INSTALLFLAG_FORCE

このフラグが設定され、関数が HardwareId 値と一致するデバイスを検出した場合、コンピューターに優れたドライバーが既に存在するかどうかに関係なく、この関数はデバイスの新しいドライバーをインストールします。

大事な このフラグは、細心の注意を払って使用してください。 このフラグを設定すると、新しいドライバーが使用可能になった後にユーザーがベンダーのアプリケーションを実行した場合、古いドライバーが新しいドライバーにインストールされる可能性があります。
 

INSTALLFLAG_READONLY

このフラグが設定されている場合、関数はインストール ファイルのコピー、名前変更、または削除を行いません。 このフラグの使用は、"埋め込み" オペレーティング システムなど、ファイル アクセスが制限されている環境または不可能な環境に限定する必要があります。

INSTALLFLAG_NONINTERACTIVE

このフラグが設定されている場合、UI の表示試行が検出されると、関数は FALSE を 返します。 このフラグは、UI を表示できないコンポーネント (サービスなど) から関数が呼び出される場合にのみ設定します。

メモ このフラグを設定し、UI 表示を試みると、デバイスが不確定状態のままになる可能性があります。
 
InstallFlags パラメーターは通常 0 です。

[out, optional] bRebootRequired

再起動が必要かどうか、および要求する必要があるユーザーを示す BOOL 型の変数へのポインター。 このポインターは省略可能であり、 NULL にすることができます。

ポインターが NULL の場合、 UpdateDriverForPlugAndPlayDevices は、必要に応じてドライバーのインストール後に再起動を求めます。 ポインターが指定されている場合、システムを再起動する必要がある場合、関数は TRUE の BOOLEAN 値を返します。 再起動を求めるのは呼び出し元の責任です。

詳細については、次の 「解説 」セクションを参照してください。

戻り値

デバイスが指定したドライバーにアップグレードされた場合、この関数は TRUE を 返します。

それ以外の場合は FALSE を 返し、ログに記録されたエラーは GetLastError の呼び出しで取得できます。 GetLastError によって返される可能性のあるエラー値を次の表に示します。

リターン コード 説明
ERROR_FILE_NOT_FOUND
 FullInfPath に指定されたパスが存在しません。
ERROR_IN_WOW64
 呼び出し元のアプリケーションは、64 ビット環境で実行を試みる 32 ビット アプリケーションであり、許可されていません。
ERROR_INVALID_FLAGS
 InstallFlags に指定された値が無効です。
ERROR_NO_SUCH_DEVINST
 HardwareId に指定された値が、システム上のどのデバイスにも一致しません。 つまり、デバイスが接続されていません。
ERROR_NO_MORE_ITEMS
 関数で HardwareId 値の一致が見つかりましたが、指定されたドライバーが現在のドライバーよりも適切に一致しておらず、呼び出し元が INSTALLFLAG_FORCE フラグを指定しませんでした。

注釈

UpdateDriverForPlugAndPlayDevices は、システム上のデバイスをスキャンし、指定された HardwareId 値に一致するすべてのデバイスに対して FullInfPath で指定されたドライバーのインストールを試みます。

既定の動作では、指定したドライバーが現在インストールされているドライバーよりも適切に一致し、指定したドライバーが %SystemRoot%\ inf のどのドライバーよりも一致する場合にのみ、指定したドライバーをインストールします。 詳細については、「 Windows でドライバーを選択する方法」を参照してください。

UpdateDriverForPlugAndPlayDevices を使用して、指定された HardwareId 値を持つデバイスが接続されているかどうかを判断することもできます。 詳細については、「 デバイス インストール アプリケーションの作成」を参照してください。

UpdateDriverForPlugAndPlayDevices は、 指定 したデバイス、デバイスのすべての子、およびデバイスの削除関係の再帰的な一部である他のすべてのデバイスに、IRP_MN_QUERY_REMOVE_DEVICE要求を送信します。 これらのデバイスのいずれかがクエリ削除要求に失敗した場合、 UpdateDriverForPlugAndPlayDevices は 、デバイスのSP_DEVINSTALL_PARAMS構造体の Flags メンバーに DI_NEEDREBOOT フラグを設定します。 削除関係の詳細については、 IRP_MN_QUERY_DEVICE_RELATIONS 要求に関するページを参照してください。

一般に、デバイス インストール アプリケーションでは、bRebootRequired に NULL を指定する必要があります。 そのため、システムは必要に応じて再起動を開始します。 アプリケーションでは、次の場合 にのみ ポインター値を指定する必要があります。

  • アプリケーションは、インストールを完了するために UpdateDriverForPlugAndPlayDevices を複数回呼び出す必要があります。
  • 再起動 (必要な場合) が発生する前に、アプリケーションで他の操作を実行する必要があります。
  • アプリケーションはクラス インストーラーであり、再起動が必要な場合は SP_DEVINSTALL_PARAMSでDI_NEEDREBOOT を設定する必要があります。
アプリケーションで UpdateDriverForPlugAndPlayDevices を複数回呼び出す必要がある場合は、受信した TRUE の再起動状態値を保存し、最後の呼び出しが返された後に再起動を求めるメッセージが表示されます。

関数が 32 ビット アプリケーションでERROR_IN_WOW64を返す場合、アプリケーションは 64 ビット システムで実行されます。これは許可されません。 詳細については、「 64 ビット システムへのデバイスのインストール」を参照してください。

要件

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