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）列舉值。 此標識碼可以是列舉值的全域唯一標識碼 （GUID） 或符號名稱。 例如，“PCI” 可用來指定PCI PnP列舉值。 PnP 列舉值的其他符號名稱範例包括 “USB”、“PCMCIA” 和 “SCSI”。
- PnP 裝置實例識別碼。 指定 PnP 裝置實例識別碼時，必須在 Flags 參數中設定DIGCF_DEVICEINTERFACE。
如需如何設定
[in, optional] hwndParent
最上層視窗的句柄，用於與在裝置資訊集中安裝裝置實例相關聯的使用者介面。 此句柄是選擇性的，而且可以 NULL。
[in] Flags
類型為 DWORD 的變數，指定篩選新增至裝置資訊集之裝置資訊元素的控制選項。 此參數可以是下列一或多個旗標的位 OR。 如需結合這些控件選項的詳細資訊，請參閱下列
DIGCF_ALLCLASSES
傳回指定裝置安裝類別或裝置介面類別的已安裝裝置清單。
DIGCF_DEVICEINTERFACE
傳回支援指定裝置介面類別之裝置介面的裝置。 如果 列舉值 參數指定 裝置實例標識符，則必須在 Flags 參數中設定此旗標。
DIGCF_DEFAULT
如果已設定裝置介面，則只傳回與系統默認裝置介面相關聯的裝置。
DIGCF_PRESENT
只傳回目前存在的裝置。
DIGCF_PROFILE
只傳回屬於目前硬體配置檔一部分的裝置。
[in, optional] DeviceInfoSet
現有 裝置資訊的句柄，SetupDiGetClassDevsEx 新增要求的裝置資訊元素。 這個參數是選擇性的，而且可以設定為 NULL。 如需使用此參數的詳細資訊，請參閱下列
[in, optional] MachineName
常數位符串的指標，其中包含裝置所在的遠端計算機名稱。 MachineNameNULL 的值會指定裝置安裝在本機電腦上。 從 Windows 8 和 Windows Server 2012 開始，不支持遠端電腦。
謹慎
從 Windows 8 和 Windows Server 2012 開始，不支援使用此函式來存取遠端電腦，因為此功能已移除。
Reserved
保留供內部使用。 這個參數必須設定為 NULL。
傳回值
如果作業成功，SetupDiGetClassDevsEx 會將句柄傳回 裝置資訊集，其中包含符合所提供參數的所有已安裝裝置。 如果作業失敗，函式會傳回INVALID_HANDLE_VALUE。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
言論
SetupDiGetClassDevsEx 呼叫 SetupDiDestroyDeviceInfoList不再需要時，必須刪除傳回的裝置資訊。
如果 DeviceInfoSetNULL，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旗標，並使用 列舉值 參數來提供裝置的 裝置實例標識碼。若要包含所有可能的裝置，請將 列舉值 設定為 NULL。
在支援裝置介面類別的裝置安裝類別中擷取裝置
安裝程式可以使用 SetupDiGetClassDevsEx 來擷取支援指定裝置介面類別之特定裝置安裝類別的裝置清單。 例如，若要擷取本機計算機上支援「掛接裝置」介面類別中裝置介面且屬於「磁碟區」裝置設定類別成員的所有裝置清單，安裝程式應該執行下列作業：- 呼叫 SetupDiCreateDeviceInfoList，為 “Volume” 裝置設定類別建立空的裝置資訊集。 將 classGuid 設定為 “Volume” 裝置設定類別的類別 GUID 指標，並視需要設定 hwndParent。 為了回應這類呼叫，函式會將輸入 HDEVINFO 的句柄傳回裝置資訊集。
- 使用下列設定呼叫 SetupDiGetClassDevsEx：
- 將 classGuid 設定為「掛接裝置」裝置介面類別類別之類別 GUID 的指標。
- 將 旗標 設定為 DIGCF_DEVICEINTERFACE。
- 將 DeviceInfoSet 設定為步驟 （1） 中取得的 HDEVINFO 句柄。
- 視需要設定 hwndParent，並將其餘參數設定為 NULL。
注意
setupapi.h 標頭會根據 UNICODE 預處理器常數的定義，將 SetupDiGetClassDevsEx 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Microsoft Windows 2000 和更新版本的 Windows 中提供。 |
| 目標平臺 | 桌面 |
| 標頭 | setupapi.h （包括 Setupapi.h） |
| 連結庫 | Setupapi.lib |