SetupDiGetClassDevsW 関数 (setupapi.h)

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

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 パラメーターで設定する必要があります。

このポインターは省略可能であり、 NULL にすることができます。列挙値を使用してデバイスを選択しない場合は、列挙子を NULL に設定します

列挙子の値を設定する方法の詳細については、次の「解説」セクションを参照してください。

[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 を指定します。関数は、このようなデバイスを表すデバイス情報要素をデバイス情報セットに追加し、指定したクラスのデバイスインターフェイスを、そのデバイス情報要素のデバイスインターフェイスリストに追加します。

さらに、次のフィルターオプションを使用して、 SetupDiGetClassDevs がデバイスインターフェイスクラスのシステムの既定のインターフェイスをサポートするデバイスのみを返すかどうかを制御できます。

システムの既定のインターフェイスをサポートするデバイスのみを返すには、指定したデバイスインターフェイスクラスに対して設定されている場合は、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) に属していないすべてのデバイスの一覧を作成します。

メモClassGuid パラメーターを GUID_DEVCLASS_UNKNOWN に設定して、不明なセットアップクラスを持つデバイスを検出することはできません。代わりに、この例に従う必要があります。

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で導入)

こちらもご覧ください

デバイス情報セット

デバイスインスタンス ID

SetupDiCreateDeviceInfoList

SetupDiDestroyDeviceInfoList

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevsEx

SetupDiGetClassDevsW 関数 (setupapi.h)

構文

パラメーター

DIGCF_ALLCLASSES

DIGCF_DEVICEINTERFACE

DIGCF_DEFAULT

DIGCF_PRESENT

DIGCF_PROFILE

戻り値

解説

デバイスセットアップクラスのコントロールオプション

デバイスインターフェイスクラスのコントロールオプション

例

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース

SetupDiGetClassDevsW 関数 (setupapi.h)

構文

パラメーター

DIGCF_ALLCLASSES

DIGCF_DEVICEINTERFACE

DIGCF_DEFAULT

DIGCF_PRESENT

DIGCF_PROFILE

戻り値

解説

デバイス セットアップ クラスのコントロール オプション

デバイス インターフェイス クラスのコントロール オプション

例

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース

デバイスセットアップクラスのコントロールオプション

デバイスインターフェイスクラスのコントロールオプション