SetupDiGetClassDevsA 函式 （setupapi.h）
SetupDiGetClassDevs 函式會傳回 裝置資訊集的句柄，其中包含本機計算機所要求的裝置資訊元素。
語法
WINSETUPAPI HDEVINFO SetupDiGetClassDevsA(
const GUID *ClassGuid,
PCSTR Enumerator,
HWND hwndParent,
DWORD Flags
);
參數
ClassGuid
裝置安裝類別的 GUID 指標， 或 裝置介面類別。 此指標是選擇性的，而且可以 NULL。 如需如何設定 ClassGuid
Enumerator
指定之 NULL 終止字串的指標：
- 隨插即用 （PnP） 的識別碼（ID）列舉值。 此識別碼可以是值的全域唯一標識碼 （GUID） 或符號名稱。 例如，“PCI” 可用來指定PCI PnP值。 PnP 值符號名稱的其他範例包括 “USB”、“PCMCIA” 和 “SCSI”。
-
的 PnP
裝置實例識別碼。 指定 PnP 裝置實例識別碼時，必須在 Flags 參數中設定DIGCF_DEVICEINTERFACE。
如需如何設定
hwndParent
最上層視窗的句柄，用於與在裝置資訊集中安裝裝置實例相關聯的使用者介面。 此句柄是選擇性的，而且可以 NULL。
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。 函式會新增至裝置資訊集代表這類裝置的裝置資訊元素，然後將指定類別的裝置介面新增至該裝置資訊元素的裝置介面清單。
- 若只傳回支援系統預設介面的裝置，如果已設定，則為指定的裝置介面類別設定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）。
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-2 （在 Windows 10 版本 10.0.14393 中引進） |