DiUninstallDevice 関数 (newdev.h)

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

DiUninstallDevice 関数は、デバイスをアンインストールし、そのデバイスノード (devnode) をシステムから削除します。これは、呼び出し時に存在する子 devnode に加えてデバイスノードのアンインストールを試みるため、DIF_REMOVE コードで SetupDiCallClassInstaller を使用する場合とは異なります。

Windows 8する前に、呼び出し時に存在しない子デバイスはアンインストールされません。ただし、Windows 8 以降では、呼び出し時に存在しない子デバイスはすべてアンインストールされます。

構文

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

パラメーター

[in] hwndParent

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

[in] DeviceInfoSet

デバイス情報要素を含むデバイス情報セットへのハンドル。この要素は、この呼び出しによってアンインストールされるデバイスを表します。

[in] DeviceInfoData

アンインストール要求が実行される、指定したデバイス情報セット内の指定したデバイスを表すSP_DEVINFO_DATA構造体へのポインター。

[in] Flags

デバイスアンインストールフラグを指定する DWORD 型の値。 Windows 7 以降では、このパラメーターを 0 に設定する必要があります。

[out, optional] NeedReboot

デバイスアンインストール要求を完了するためにシステムの再起動が必要かどうかを示すために DiUninstallDevice が設定する BOOL 型の値へのポインター。このパラメーターは省略可能であり、 NULL に設定できます。

パラメーターを指定し、システムの再起動が必要な場合、 DiUninstallDevice は 値を TRUE に設定します。この場合、アプリケーションはユーザーにシステムの再起動を求めるメッセージを表示する必要があります。このパラメーターを指定し、システムの再起動が不要な場合、 DiUninstallDevice は 値を FALSE に設定 します。

このパラメーターが NULL で、デバイスのアンインストールを完了するためにシステムの再起動が必要な場合、 DiUninstallDevice はシステム再起動ダイアログボックスを表示します。

このパラメーターの詳細については、「解説」セクションを参照してください。

戻り値

関数がデバイスを表す最上位デバイスノードを正常にアンインストールした場合、DiUninstallDevice は TRUE を返します。それ以外の場合、 DiUninstallDevice は FALSE を返し、 GetLastError を呼び出すことでログに記録されたエラーを取得できます。次の一覧は、この API に 対して GetLastError が返す可能性がある一般的なエラー値の一部を示しています。

リターンコード	説明
ERROR_ACCESS_DENIED	呼び出し元には管理者特権がありません。既定では、Windows では、呼び出し元にデバイスをアンインストールするための管理者特権が必要です。
ERROR_INVALID_FLAGS	Flags パラメーターに指定された値が 0 に等しくありません。

メモ戻り値は、すべての子 devnode の削除が成功または失敗したことを示すものではありません。 Windows Vista 以降、子 devnode の削除の状態に関する情報は 、Setupapi.dev.log ファイルで入手できます。このファイルの詳細については、「 SetupAPI Text Logs」を参照してください。

注釈

DiUninstallDevice は、DIF_REMOVE コードで使用する場合、SetupDiCallClassInstaller と同じ関数を実行します。主な違いは、最上位デバイスの子 devnode も削除される点です。 DiUninstallDevice は、最上位のデバイスノードをアンインストールできなかった場合にのみエラーを返します。これは、DIF_REMOVE コードで使用した場合の SetupDiCallClassInstaller の動作と一致します。子 devnode のアンインストールが成功したかどうかの詳細については、Setupapi.dev.log ファイルを参照してください。

アンインストールするデバイスは、参照先のデバイスを含むデバイス情報セットと、特定のデバイスの SP_DEVINFO_DATA 構造を提供することによって指定されます。これらは、 DeviceInfoSet パラメーターと DeviceInfoData パラメーターで提供されます。

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

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

デバイスのアンインストール要求でコンピューターの再起動が必要な場合、NeedReboot パラメーターが NULL に設定されている場合、DiUninstallDevice はユーザーにシステムの再起動を求めます。アプリケーションで使用されているユーザーインターフェイスウィンドウがある場合は、 hwndParent パラメーターをそのウィンドウのハンドルの値に設定する必要があります。

ただし、アプリケーションが必要なシステム再起動の通知を管理する場合は、 NeedReboot パラメーターを NULL 以外の値に設定する必要があります。 DiUninstallDevice は 、システムの再起動が必要かどうかに応じて、 NeedReboot パラメーターを TRUE または FALSE に設定します。

次の一覧は、アプリケーションがシステムの再起動を管理する理由の例を示しています。

アプリケーションでは、複数のデバイスをアンインストールする必要があります。すべてのデバイスがアンインストールされた後、DiUninstallDevice の呼び出しが NeedReboot パラメーターで TRUE を返した場合、アプリケーションはユーザーにシステムの再起動を求めるメッセージを表示する必要があります。
アプリケーションでは、システムを再起動する前に、他の操作を実行する必要があります。システムの再起動が必要な場合、アプリケーションは必要な操作を完了し、ユーザーにシステムの再起動を求めるメッセージを表示する必要があります。
アプリケーションはクラスインストーラーです。この場合、クラスインストーラーは、デバイスの SP_DEVINSTALL_PARAMS 構造体の Flags メンバーに DI_NEEDREBOOT フラグを設定する必要があります。

要件

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