SetupDiGetClassDevsW 函式 (setupapi.h)

發行項
03/05/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) 列舉值的 (識別碼) 識別碼。這個標識碼可以是值的全域唯一標識碼， (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

傳回支援指定裝置介面類別之裝置介面的裝置。如果 Enumerator 參數指定裝置實例識別碼，則必須在 Flags 參數中設定此旗標。

DIGCF_DEFAULT

如果已針對指定的裝置介面類別設定，則只傳回與系統預設裝置介面相關聯的裝置。

DIGCF_PRESENT

只傳回系統中目前存在的裝置。

DIGCF_PROFILE

只傳回屬於目前硬體配置檔一部分的裝置。

傳回值

如果作業成功， SetupDiGetClassDevs 會傳回裝置資訊的句柄，其中包含符合所提供參數的所有已安裝裝置。如果作業失敗，函式會傳回INVALID_HANDLE_VALUE。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

當呼叫 SetupDiDestroyDeviceInfoList 不再需要時，SetupDiGetClassDevs 的呼叫端必須刪除所傳回的裝置資訊。

呼叫 SetupDiGetClassDevsEx ，以擷取遠端電腦上的類別裝置。

裝置安裝類別控制選項

使用下列篩選選項來控制 SetupDiGetClassDevs 會傳回所有裝置安裝類別的裝置，還是只針對指定的裝置安裝類別傳回裝置：

若要傳回所有裝置安裝類別的裝置，請設定DIGCF_ALLCLASSES旗標，並將 ClassGuid 參數設定為 NULL。
若要只傳回特定裝置設定類別的裝置，請勿設定DIGCF_ALLCLASSES，並使用 ClassGuid 提供裝置安裝類別的 GUID。

此外，您可以使用下列篩選選項來彼此結合，進一步限制傳回哪些裝置：

若要只傳回系統中存在的裝置，請設定DIGCF_PRESENT旗標。
若要只傳回屬於目前硬體配置檔的裝置，請設定DIGCF_PROFILE旗標。
若要只傳回特定 PnP 列舉值的裝置，請使用 Enumerator 參數來提供列舉值的 GUID 或符號名稱。如果 Enumerator 為 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 參數來提供裝置的裝置實例識別碼。若要包含所有可能的裝置，請將列舉值設定為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 標頭會將 SetupDiGetClassDevs 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 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)