SetupDiGetClassDevsW 関数 (setupapi.h)
SetupDiGetClassDevs 関数は、ローカル コンピューターの要求されたデバイス情報要素を含むデバイス情報セットへのハンドルを返します。
構文
WINSETUPAPI HDEVINFO SetupDiGetClassDevsW(
[in, optional] const GUID *ClassGuid,
[in, optional] PCWSTR Enumerator,
[in, optional] HWND hwndParent,
[in] DWORD Flags
);
パラメーター
[in, optional] ClassGuid
デバイス セットアップ クラスまたはデバイスインターフェイス クラスの GUID へのポインター。 このポインターは省略可能であり、 NULL にすることができます。 ClassGuid を設定する方法の詳細については、次の「解説」セクションを参照してください。
[in, optional] Enumerator
次を指定する NULL で終わる文字列へのポインター。
- プラグ アンド プレイ (PnP) 列挙子の識別子 (ID)。 この ID には、値のグローバル一意識別子 (GUID) またはシンボリック名を指定できます。 たとえば、"PCI" を使用して PCI PnP 値を指定できます。 PnP 値のシンボリック名の他の例としては、"USB"、"PCMCIA"、"SCSI" などがあります。
- PnP デバイス インスタンス ID。 PnP デバイス インスタンス ID を指定する場合、DIGCF_DEVICEINTERFACEは Flags パラメーターで設定する必要があります。
列挙子の値を設定する方法の詳細については、次の「解説」セクションを参照してください。
[in, optional] hwndParent
デバイス情報セットへのデバイス インスタンスのインストールに関連付けられているユーザー インターフェイスに使用する最上位ウィンドウへのハンドル。 このハンドルは省略可能であり、 NULL にすることができます。
[in] Flags
デバイス情報セットに追加されるデバイス情報要素をフィルター処理するコントロール オプションを指定する DWORD 型の変数。 このパラメーターには、次のフラグの 0 個以上のビットごとの OR を指定できます。 これらのフラグの組み合わせの詳細については、次の 「解説 」セクションを参照してください。
DIGCF_ALLCLASSES
すべてのデバイス セットアップ クラスまたはすべてのデバイス インターフェイス クラスにインストールされているデバイスの一覧を返します。
DIGCF_DEVICEINTERFACE
指定したデバイス インターフェイス クラスのデバイス インターフェイスをサポートするデバイスを返します。 Enumerator パラメーターでデバイス インスタンス ID が指定されている場合は、Flags パラメーターでこのフラグを設定する必要があります。
DIGCF_DEFAULT
指定したデバイス インターフェイス クラスに対して、システムの既定のデバイス インターフェイスに関連付けられているデバイス (設定されている場合) のみを返します。
DIGCF_PRESENT
システムに現在存在するデバイスのみを返します。
DIGCF_PROFILE
現在のハードウェア プロファイルの一部であるデバイスのみを返します。
戻り値
操作が成功した場合、 SetupDiGetClassDevs は、指定されたパラメーターに一致するすべてのインストール済みデバイスを含む デバイス情報セット へのハンドルを返します。 操作が失敗した場合、関数は INVALID_HANDLE_VALUEを返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
SetupDiGetClassDevs の呼び出し元は、SetupDiDestroyDeviceInfoList を呼び出して不要になったときに、返されたデバイス情報セットを削除する必要があります。
SetupDiGetClassDevsEx を呼び出して、リモート コンピューター上のクラスのデバイスを取得します。
デバイス セットアップ クラスのコントロール オプション
次のフィルター オプションを使用して、 SetupDiGetClassDevs がすべてのデバイス セットアップ クラスのデバイスを返すか、指定したデバイス セットアップ クラスに対してのみデバイスを返すかを制御します。- すべてのデバイス セットアップ クラスのデバイスを返すには、DIGCF_ALLCLASSES フラグを設定し、 ClassGuid パラメーターを NULL に設定 します。
- 特定のデバイス セットアップ クラスに対してのみデバイスを返すには、DIGCF_ALLCLASSESを設定せず、 ClassGuid を 使用してデバイス セットアップ クラスの GUID を指定します。
- システムに存在するデバイスのみを返すには、DIGCF_PRESENT フラグを設定します。
- 現在のハードウェア プロファイルの一部であるデバイスのみを返すには、DIGCF_PROFILE フラグを設定します。
- 特定の PnP 列挙子に対してのみデバイスを返すには、Enumerator パラメーターを使用して、列挙子の GUID またはシンボリック名を指定します。 列挙子が NULL の場合、SetupDiGetClassDevs はすべての PnP 列挙子のデバイスを返します。
デバイス インターフェイス クラスのコントロール オプション
次のフィルター オプションを使用して、 SetupDiGetClassDevs が、任意のデバイス インターフェイス クラスをサポートするデバイスを返すか、指定されたデバイス インターフェイス クラスをサポートするデバイスのみを返すかを制御します。- 任意のクラスのデバイス インターフェイスをサポートするデバイスを返すには、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 に設定します。
例
SetupDiGetClassDevs 関数の使用方法の例を次に示します。
例 1: 現在存在しないデバイスを含む、システム内のすべてのデバイスの一覧を作成します。
Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES);
例 2: システムに存在するすべてのデバイスの一覧を作成します。
Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES | DIGCF_PRESENT);
例 3: ネットワーク アダプター デバイス セットアップ クラスのシステムに存在するすべてのデバイスの一覧を作成します。
Handle = SetupDiGetClassDevs(&GUID_DEVCLASS_NET, NULL, NULL, DIGCF_PRESENT);
例 4: ストレージ ボリューム デバイス インターフェイス クラスからインターフェイスを有効にしたシステムに存在するすべての デバイスの一覧を作成します。
Handle = SetupDiGetClassDevs(&GUID_DEVINTERFACE_VOLUME, NULL, NULL, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);
例 5: システムに存在するが、既知の デバイス セットアップ クラス (Windows Vista 以降のバージョンの Windows) に属していないすべてのデバイスの一覧を作成します。
DeviceInfoSet = SetupDiGetClassDevs(
NULL,
NULL,
NULL,
DIGCF_ALLCLASSES | DIGCF_PRESENT);
ZeroMemory(&DeviceInfoData, sizeof(SP_DEVINFO_DATA));
DeviceInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
DeviceIndex = 0;
while (SetupDiEnumDeviceInfo(
DeviceInfoSet,
DeviceIndex,
&DeviceInfoData)) {
DeviceIndex++;
if (!SetupDiGetDeviceProperty(
DeviceInfoSet,
&DeviceInfoData,
&DEVPKEY_Device_Class,
&PropType,
(PBYTE)&DevGuid,
sizeof(GUID),
&Size,
0) || PropType != DEVPROP_TYPE_GUID) {
Error = GetLastError();
if (Error == ERROR_NOT_FOUND) {
\\
\\ This device has an unknown device setup class.
\\
}
}
}
if (DeviceInfoSet) {
SetupDiDestroyDeviceInfoList(DeviceInfoSet);
}
注意
setupapi.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SetupDiGetClassDevs を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Microsoft Windows 2000 以降のバージョンの Windows で使用できます。 |
| 対象プラットフォーム | Desktopユニバーサルの場合は、ユニバーサルCM_Get_Device_ID_ListFor呼び出し、CM_Get_Device_Interface_Listを呼び出します |
| Header | setupapi.h (SetupAPI.h を含む) |
| Library | SetupAPI.lib |
| [DLL] | SetupAPI.dll |
| API セット | ext-ms-win-setupapi-classinstallers-l1-1-0 (Windows 8で導入) |