SetupDiGetClassDevsExA 函式 (setupapi.h)

發行項
03/05/2024

SetupDiGetClassDevsEx 函式會傳回裝置資訊集的句柄，其中包含本機或遠端電腦所要求的裝置資訊元素。

語法

WINSETUPAPI HDEVINFO SetupDiGetClassDevsExA(
  [in, optional] const GUID *ClassGuid,
  [in, optional] PCSTR      Enumerator,
  [in, optional] HWND       hwndParent,
  [in]           DWORD      Flags,
  [in, optional] HDEVINFO   DeviceInfoSet,
  [in, optional] PCSTR      MachineName,
                 PVOID      Reserved
);

參數

[in, optional] ClassGuid

裝置安裝類別或裝置介面類別之 GUID 的指標。此指標是選擇性的，而且可以是 NULL。如果未使用 GUID 值來選取裝置，請將 ClassGuid 設定為 NULL。 For more information about how to use ClassGuid, see the following Remarks section.

[in, optional] Enumerator

指定之 NULL 終止字串的指標：

隨插即用 (PnP) 列舉值的標識碼 (標識碼) 。此標識碼可以是列舉值的全域唯一標識碼， (GUID) 或符號名稱。例如，“PCI” 可用來指定PCI PnP列舉值。 PnP 列舉值的其他符號名稱範例包括 “USB”、“PCMCIA” 和 “SCSI”。
PnP 裝置實例標識碼。指定 PnP 裝置實例識別碼時，必須在 Flags 參數中設定DIGCF_DEVICEINTERFACE。

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

For more information about how to set the Enumerator value, see the following Remarks section.

[in, optional] hwndParent

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

[in] Flags

類型為 DWORD 的變數，指定篩選新增至裝置資訊集之裝置資訊專案的控件選項。此參數可以是下列一或多個旗標的位 OR。 For more information about combining these control options, see the following Remarks section.

DIGCF_ALLCLASSES

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

DIGCF_DEVICEINTERFACE

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

DIGCF_DEFAULT

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

DIGCF_PRESENT

只傳回目前存在的裝置。

DIGCF_PROFILE

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

[in, optional] DeviceInfoSet

SetupDiGetClassDevsEx 所設定之現有裝置資訊集的句柄會新增要求的裝置資訊元素。這個參數是選擇性的，而且可以設定為 NULL。 For more information about using this parameter, see the following Remarks section.

[in, optional] MachineName

常數位符串的指標，其中包含裝置所在遠端計算機的名稱。 MachineName 的 NULL 值會指定裝置安裝在本機電腦上。

警告

從 Windows 8 和 Windows Server 2012 開始，不支援使用此函式來存取遠端計算機，因為此功能已移除。

Reserved

保留供內部使用。此參數必須設定為 NULL。

傳回值

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

備註

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

如果 DeviceInfoSet 為 NULL，SetupDiGetClassDevsEx 會建立新的裝置資訊集，其中包含擷取的裝置資訊元素，並傳回新裝置資訊集的句柄。如果呼叫端要求函式擷取 ClassGuid 參數所提供裝置安裝類別的裝置，則函式會將新裝置資訊的裝置安裝類別設定為提供的類別 GUID。

如果 DeviceInfoSet 未設定為 NULL，函式會將擷取的裝置資訊元素新增至與所提供句柄相關聯的裝置資訊集，並傳回提供的句柄。如果 ClassGuid 提供裝置安裝類別，則提供的裝置資訊集的裝置安裝類別必須設定為提供的類別 GUID。

裝置設定類別控制選項

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

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

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

若只要傳回系統中存在的裝置，請設定DIGCF_PRESENT旗標。
若只要傳回屬於目前硬體配置檔一部分的裝置，請設定DIGCF_PROFILE旗標。
若要只傳回特定 PnP 列舉值的裝置，請使用 Enumerator 參數來提供列舉值的 GUID 或符號名稱。如果 Enumerator 為 NULL，SetupDiGetClassDevsEx 會傳回所有 PnP 列舉值的裝置。

裝置介面類別控制選項

使用下列篩選選項來控制 SetupDiGetClassDevsEx 是否傳回支援任何裝置介面類別的裝置，或只傳回支援指定裝置介面類別的裝置：

若要傳回支援任何類別之裝置介面的裝置，請設定DIGCF_DEVICEINTERFACE旗標、設定DIGCF_ALLCLASSES旗標，並將 ClassGuid 設定為 NULL。函式會將裝置資訊新增至裝置資訊設定代表這類裝置的裝置資訊元素，然後將裝置資訊元素新增至裝置資訊元素，其中包含裝置支援的所有裝置介面。
若只要傳回支援指定類別之裝置介面的裝置，請設定 DIGCF_DEVICEINTERFACE 旗標，並使用 ClassGuid 參數來提供裝置介面類別的類別 GUID。函式會將裝置資訊新增至裝置資訊集，該裝置資訊元素代表這類裝置，然後將指定類別的裝置介面新增至該裝置資訊元素的裝置介面清單。

此外，您可以使用下列篩選選項來控制 SetupDiGetClassDevsEx 是否只傳回支援裝置介面類別系統預設介面的裝置：

若要只傳回支援系統預設介面的裝置，如果已設定，則為指定的裝置介面類別設定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，並將其餘參數設定為 NULL。

在這個類型的作業中，如果裝置的裝置安裝類別與提供的裝置資訊集相同，而且裝置支持類別與指定裝置介面類別相同的裝置介面， 則 SetupDiGetClassDevsEx 會傳回裝置。

注意

setupapi.h 標頭會將 SetupDiGetClassDevsEx 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	可在 Microsoft Windows 2000 和更新版本的 Windows 中使用。
目標平台	桌面
標頭	setupapi.h (包括 Setupapi.h)
程式庫	Setupapi.lib