SetupDiGetClassDevsW 函式（setupapi.h）

發行項
11/20/2024

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）列舉值。此識別碼可以是值的全域唯一標識碼（GUID）或符號名稱。例如，“PCI” 可用來指定PCI PnP值。 PnP 值符號名稱的其他範例包括 “USB”、“PCMCIA” 和 “SCSI”。
的 PnP 裝置實例識別碼。指定 PnP 裝置實例識別碼時，必須在 Flags 參數中設定DIGCF_DEVICEINTERFACE。

此指標是選擇性的，而且可以 NULL。如果未使用列舉值來選取裝置，請將列舉值設定為 NULL

如需如何設定列舉值值的詳細資訊，請參閱下列 < 備註> 一節。

[in, optional] hwndParent

最上層視窗的句柄，用於與在裝置資訊集中安裝裝置實例相關聯的使用者介面。此句柄是選擇性的，而且可以 NULL。

[in] Flags

類型為 DWORD 的變數，指定篩選新增至裝置資訊集之裝置資訊元素的控制選項。這個參數可以是零個或多個下列旗標的位 OR。如需合併這些旗標的詳細資訊，請參閱下列一節。

DIGCF_ALLCLASSES

傳回所有裝置安裝類別或所有裝置介面類別的已安裝裝置清單。

DIGCF_DEVICEINTERFACE

傳回支援指定裝置介面類別之裝置介面的裝置。如果 列舉值 參數指定裝置實例標識符，則必須在 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 列舉值的裝置，請使用 列舉值 參數來提供列舉值的 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旗標，並使用 列舉值 參數來提供裝置的裝置實例標識碼。若要包含所有可能的裝置，請將 列舉值 設定為 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 預處理器常數的定義，將 SetupDiGetClassDevs 定義為自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Microsoft Windows 2000 和更新版本的 Windows 中提供。
目標平臺	DesktopFor universal， call CM_Get_Device_ID_ListFor universal， call CM_Get_Device_Interface_List
標頭	setupapi.h （包括 SetupAPI.h）
連結庫	SetupAPI.lib
DLL	SetupAPI.dll
API 集	ext-ms-win-setupapi-classinstallers-l1-1-0 （在 Windows 8 中引進）

另請參閱

裝置資訊集

裝置實例標識碼

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

傳回值

言論

裝置設定類別控制選項

裝置介面類別控制選項

例子

要求

另請參閱

意見反應

其他資源

SetupDiGetClassDevsW 函式（setupapi.h）