SetupDiGetClassDevsExW 関数 (setupapi.h)
SetupDiGetClassDevsEx 関数は、ローカルまたはリモート コンピューターの要求されたデバイス情報要素を含むデバイス情報セットへのハンドルを返します。
構文
WINSETUPAPI HDEVINFO SetupDiGetClassDevsExW(
[in, optional] const GUID *ClassGuid,
[in, optional] PCWSTR Enumerator,
[in, optional] HWND hwndParent,
[in] DWORD Flags,
[in, optional] HDEVINFO DeviceInfoSet,
[in, optional] PCWSTR MachineName,
PVOID Reserved
);
パラメーター
[in, optional] ClassGuid
デバイス セットアップ クラスまたはデバイスインターフェイス クラスの GUID へのポインター。 このポインターは省略可能であり、 NULL にすることができます。 GUID 値を使用してデバイスを選択しない場合は、 ClassGuid を NULL に設定します。 ClassGuid の使用方法の詳細については、次の「解説」セクションを参照してください。
[in, optional] Enumerator
次を指定する NULL で終わる文字列へのポインター。
- プラグ アンド プレイ (PnP) 列挙子の識別子 (ID)。 この ID には、列挙子のグローバル一意識別子 (GUID) またはシンボリック名を指定できます。 たとえば、"PCI" を使用して PCI PnP 列挙子を指定できます。 PnP 列挙子のシンボリック名の他の例としては、"USB"、"PCMCIA"、"SCSI" などがあります。
- PnP デバイス インスタンス ID。 PnP デバイス インスタンス ID を指定する場合は、flags パラメーターでDIGCF_DEVICEINTERFACEを設定する必要があります。
列挙子の値を設定する方法の詳細については、次の「解説」セクションを参照してください。
[in, optional] hwndParent
デバイス情報セットへのデバイス インスタンスのインストールに関連付けられているユーザー インターフェイスに使用される最上位ウィンドウへのハンドル。 このハンドルは省略可能であり、 NULL にすることができます。
[in] Flags
デバイス情報セットに追加されるデバイス情報要素をフィルター処理する制御オプションを指定する DWORD 型の変数。 このパラメーターには、次のフラグの 1 つ以上のビットごとの OR を指定できます。 これらのコントロール オプションの組み合わせの詳細については、次の 「解説 」セクションを参照してください。
DIGCF_ALLCLASSES
指定したデバイス セットアップ クラスまたはデバイス インターフェイス クラスにインストールされているデバイスの一覧を返します。
DIGCF_DEVICEINTERFACE
指定したデバイス インターフェイス クラスのデバイス インターフェイスをサポートするデバイスを返します。 Enumerator パラメーターでデバイス インスタンス ID が指定されている場合は、Flags パラメーターでこのフラグを設定する必要があります。
DIGCF_DEFAULT
指定したデバイス インターフェイス クラスに対して、システムの既定のデバイス インターフェイスに関連付けられているデバイス (設定されている場合) のみを返します。
DIGCF_PRESENT
現在存在するデバイスのみを返します。
DIGCF_PROFILE
現在のハードウェア プロファイルの一部であるデバイスのみを返します。
[in, optional] DeviceInfoSet
SetupDiGetClassDevsEx が要求されたデバイス情報要素を追加する既存のデバイス情報セットへのハンドル。 このパラメーターは省略可能であり、 NULL に設定できます。 このパラメーターの使用方法の詳細については、次の 「解説 」セクションを参照してください。
[in, optional] MachineName
デバイスが存在するリモート コンピューターの名前を含む定数文字列へのポインター。 MachineName の値 NULL は、デバイスがローカル コンピューターにインストールされていることを指定します。 リモート コンピューターは、Windows 8 および Windows Server 2012 以降ではサポートされていません。
注意事項
この機能は削除されたため、この関数を使用してリモート マシンにアクセスすることは、Windows 8とWindows Server 2012以降はサポートされていません。
Reserved
内部使用のために予約されています。 このパラメーターは NULL に設定する必要があります。
戻り値
操作が成功すると、 SetupDiGetClassDevsEx は、指定されたパラメーターに一致するすべてのインストール済みデバイスを含む デバイス情報セット へのハンドルを返します。 操作が失敗した場合、関数はINVALID_HANDLE_VALUEを返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
SetupDiGetClassDevsEx の呼び出し元は、SetupDiDestroyDeviceInfoList を呼び出して不要になったときに、返されたデバイス情報セットを削除する必要があります。
DeviceInfoSet が NULL の場合、SetupDiGetClassDevsEx は、取得したデバイス情報要素を含む新しいデバイス情報セットを作成し、新しいデバイス情報セットへのハンドルを返します。 呼び出し元が ClassGuid パラメーターによって提供されるデバイス セットアップ クラスのデバイスを取得するように関数が要求した場合、関数は、指定されたクラス GUID に設定された新しいデバイス情報のデバイス セットアップ クラスを設定します。
DeviceInfoSet が NULL に設定されていない場合、関数は、取得したデバイス情報要素を、指定されたハンドルに関連付けられているデバイス情報セットに追加し、指定されたハンドルを返します。 ClassGuid がデバイス セットアップ クラスを提供する場合は、指定されたデバイス情報セットのデバイス セットアップ クラスを、指定されたクラス GUID に設定する必要があります。
デバイス セットアップ クラスのコントロール オプション
次のフィルター オプションを使用して、 SetupDiGetClassDevsEx がすべてのデバイス セットアップ クラスのデバイスを返すか、指定したデバイス セットアップ クラスに対してのみデバイスを返すかを制御します。- すべてのデバイス セットアップ クラスのデバイスを返すには、DIGCF_ALLCLASSES フラグを設定し、 ClassGuid パラメーターを NULL に設定 します。
- 特定のデバイス セットアップ クラスに対してのみデバイスを返すには、DIGCF_ALLCLASSESを設定せず 、ClassGuid を 使用してデバイス セットアップ クラスの GUID を指定します。
- システムに存在するデバイスのみを返すには、DIGCF_PRESENT フラグを設定します。
- 現在のハードウェア プロファイルの一部であるデバイスのみを返すには、DIGCF_PROFILE フラグを設定します。
- 特定の PnP 列挙子のデバイスのみを返すには、列挙子パラメーターを使用して、列挙子の GUID またはシンボリック名を指定します。 列挙子が NULL の場合、SetupDiGetClassDevsEx はすべての PnP 列挙子のデバイスを返します。
デバイス インターフェイス クラスのコントロール オプション
次のフィルター オプションを使用して、 SetupDiGetClassDevsEx が任意のデバイス インターフェイス クラスをサポートするデバイスを返すか、指定したデバイス インターフェイス クラスをサポートするデバイスのみを返すかを制御します。- 任意のクラスのデバイス インターフェイスをサポートするデバイスを返すには、DIGCF_DEVICEINTERFACE フラグを設定し、DIGCF_ALLCLASSES フラグを設定し、 ClassGuid を NULL に設定 します。 関数は、このようなデバイスを表すデバイス情報要素をデバイス情報セットに追加し、デバイスがサポートするすべてのデバイス インターフェイスを含むデバイス インターフェイス リストをデバイス情報要素に追加します。
- 指定したクラスのデバイス インターフェイスをサポートするデバイスのみを返すには、DIGCF_DEVICEINTERFACE フラグを設定し 、ClassGuid パラメーターを使用してデバイス インターフェイス クラスのクラス GUID を指定します。 関数は、このようなデバイスを表すデバイス情報要素をデバイス情報セットに追加し、指定したクラスのデバイス インターフェイスを、そのデバイス情報要素のデバイス インターフェイス リストに追加します。
- システムの既定のインターフェイスをサポートするデバイスのみを返すには、指定したデバイス インターフェイス クラスに対して設定されている場合は、DIGCF_DEVICEINTERFACE フラグを設定し、DIGCF_DEFAULT フラグを設定し、 ClassGuid を 使用してデバイス インターフェイス クラスのクラス GUID を指定します。 関数は、このようなデバイスを表すデバイス情報要素をデバイス情報セットに追加し、そのデバイス情報要素のデバイス インターフェイス リストにシステムの既定のインターフェイスを追加します。
- 指定されていないデバイス インターフェイス クラスのシステムの既定のインターフェイスをサポートするデバイスを返すには、DIGCF_DEVICEINTERFACE フラグを設定し、DIGCF_ALLCLASSES フラグを設定し、DIGCF_DEFAULT フラグを設定し、 ClassGuid を NULL に設定 します。 関数は、このようなデバイスを表すデバイス情報要素をデバイス情報セットに追加し、そのデバイス情報要素のデバイス インターフェイス リストにシステムの既定のインターフェイスを追加します。
- システムに存在するデバイスのみを返すには、DIGCF_PRESENT フラグを設定します。
- 現在のハードウェア プロファイルの一部であるデバイスのみを返すには、DIGCF_PROFILE フラグを設定します。
- 特定のデバイスのみを返すには、DIGCF_DEVICEINTERFACE フラグを設定し、 Enumerator パラメーターを使用して デバイスのデバイス インスタンス ID を 指定します。 使用可能なすべてのデバイスを含めるには、 列挙子 を NULL に設定します。
デバイス インターフェイス クラスをサポートするデバイス セットアップ クラス内のデバイスの取得
インストーラーは 、SetupDiGetClassDevsEx を使用して、指定したデバイス インターフェイス クラスのデバイス インターフェイスをサポートする特定のデバイス セットアップ クラスのデバイスの一覧を取得できます。 たとえば、"マウントされたデバイス" インターフェイス クラスのデバイス インターフェイスをサポートし、"ボリューム" デバイス セットアップ クラスのメンバーであるローカル コンピューター上のすべてのデバイスの一覧を取得するには、インストーラーで次の操作を実行する必要があります。- SetupDiCreateDeviceInfoList を呼び出して、"ボリューム" デバイス セットアップ クラスの空のデバイス情報セットを作成します。 ClassGuid を "Volume" デバイス セットアップ クラスのクラス GUID へのポインターに設定し、必要に応じて hwndParent を設定します。 このような呼び出しに応答して、 関数は HDEVINFO 型のハンドルをデバイス情報セットに返します。
- 次の設定で SetupDiGetClassDevsEx を呼び出します。
- ClassGuid を、"マウントされたデバイス" デバイス インターフェイス クラスのクラス GUID へのポインターに設定します。
- [フラグ] を [DIGCF_DEVICEINTERFACE] に設定します。
- 手順 (1) で取得した HDEVINFO ハンドルに DeviceInfoSet を設定します。
- 必要に応じて hwndParent を設定し、残りのパラメーターを NULL に設定します。
注意
setupapi.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SetupDiGetClassDevsEx を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Microsoft Windows 2000 以降のバージョンの Windows で使用できます。 |
| 対象プラットフォーム | デスクトップ |
| Header | setupapi.h (Setupapi.h を含む) |
| Library | Setupapi.lib |