CM_Get_Device_ID_ListW函式 (cfgmgr32.h)
CM_Get_Device_ID_List函式會擷取本機電腦裝置實例的裝置實例標識碼清單。
語法
CMAPI CONFIGRET CM_Get_Device_ID_ListW(
[in, optional] PCWSTR pszFilter,
[out] PZZWSTR Buffer,
[in] ULONG BufferLen,
[in] ULONG ulFlags
);
參數
[in, optional] pszFilter
呼叫端提供的字元字串指標,其設定為計算機裝置實例標識碼的子集, (標識元) 或 NULL。 請參閱 ulFlags 的下列描述。
[out] Buffer
緩衝區位址,以接收一組以NULL終止的裝置實例標識符字串。 集合的結尾會以額外的 NULL終止。 呼叫 CM_Get_Device_ID_List_Size,即可取得所需的緩衝區大小。
[in] BufferLen
由呼叫端提供的緩衝區長度,以字元為單位,由 Buffer 所指定的 緩衝區。
[in] ulFlags
下列其中一個呼叫端提供的位旗標,指定搜尋篩選:
CM_GETIDLIST_FILTER_BUSRELATIONS
如果設定此旗標, pszFilter 必須指定裝置實例標識符。 函式會傳回指定裝置實例 之總線關聯 性裝置實例的裝置實例標識碼。
CM_GETIDLIST_FILTER_CLASS (Windows 7 和更新版本的 Windows)
如果設定此旗標, pszFilter 會包含指定 裝置安裝類別 GUID 的字串。 傳回的清單包含裝置實例,CM_DRP_CLASSGUID常數所參考的屬性 () 符合指定的裝置設定類別 GUID。
CM_DRP_CLASSGUID常數定義於 Cfgmgr32.h 中。
CM_GETIDLIST_FILTER_PRESENT (Windows 7 和更新版本的 Windows)
如果設定此旗標,傳回的清單只會包含系統上目前存在的裝置實例。 此值可以與其他 ulFlags 值結合,例如CM_GETIDLIST_FILTER_CLASS。
CM_GETIDLIST_FILTER_TRANSPORTRELATIONS (Windows 7 和更新版本的 Windows)
如果設定此旗標, pszFilter 必須指定複合裝置節點的裝置實例標識碼, (devnode) 。
函式會傳回 devnode 的裝置實例識別碼,這些標識碼代表指定之複合開發節點的傳輸關聯性。
For more information about composite devnodes and transport relations, see the following Remarks section.
CM_GETIDLIST_DONOTGENERATE
僅與CM_GETIDLIST_FILTER_SERVICE搭配使用。 如果已設定,且裝置樹狀結構未包含指定服務的 devnode,則此旗標會防止函式為服務建立 devnode。
CM_GETIDLIST_FILTER_EJECTRELATIONS
如果設定此旗標, pszFilter 必須指定裝置實例標識符。 函式會針對指定裝置實例的 退出關聯 傳回裝置實例標識碼。
CM_GETIDLIST_FILTER_ENUMERATOR
如果設定此旗標, pszFilter 必須指定裝置列舉值的名稱,選擇性地後面接著 裝置標識碼。 字串格式為 EnumeratorName\<DeviceID>,例如 ROOT 或 ROOT\*PNP0500。
如果 pszFilter 只提供列舉值名稱,函式會傳回與列舉值相關聯之每個裝置實例的 裝置實例 識別碼。 您可以呼叫 CM_Enumerate_Enumerators 來取得列舉值名稱。
如果 pszFilter 同時提供列舉值和 裝置識別碼,函式只會針對與列舉值相關聯的指定裝置實例傳回 裝置實例 識別符。
CM_GETIDLIST_FILTER_NONE
如果設定此旗標, 則會忽略 pszFilter ,並傳回系統上所有裝置的清單。
CM_GETIDLIST_FILTER_POWERRELATIONS
如果設定此旗標, pszFilter 必須指定裝置實例標識符。 函式會針對指定裝置實例的電源關聯傳回裝置實例標識碼。
CM_GETIDLIST_FILTER_REMOVALRELATIONS
如果設定此旗標, pszFilter 必須指定裝置實例標識符。 函式會傳回裝置實例標識碼,以取得指定之裝置實例的 移除關聯 性。
CM_GETIDLIST_FILTER_SERVICE
如果設定此旗標, pszFilter 必須指定 Microsoft Windows 服務的名稱, (通常是驅動程式) 。 函式會傳回由指定服務所控制之裝置實例的裝置實例標識碼。
請注意,如果裝置樹狀結構未包含指定服務的 devnode ,此函式預設會建立一個。 若要禁止此行為,也請設定CM_GETIDLIST_DONOTGENERATE。
如果未指定搜尋篩選旗標,函式會傳回所有裝置實例的所有裝置實例標識碼。
傳回值
如果作業成功,函式會傳回CR_SUCCESS。 否則,它會傳回 Cfgmgr32.h 中定義的其中一個CR_前置錯誤碼。
備註
從 Windows 7 開始,支援多個封包型數據的傳輸路徑的裝置稱為 複合 裝置,並以 複合 開發節點表示。 複合開發節點以邏輯方式將複合裝置以單一裝置的形式表示給使用者和應用程式,即使複合開發節點可以有多個實體裝置的路徑也一樣。
實體裝置的每個作用中傳輸路徑都會以傳輸開發節點表示,並稱為複合裝置的 傳輸關聯 性。
複合開發節點 (但不是相關的傳輸開發節點,) 向應用程式和系統公開裝置介面。 當應用程式使用這些公用裝置介面時,複合裝置會將封包型數據路由傳送至其中一或多個傳輸開發節點,然後將數據傳輸至實體裝置。
例如,如果實體行動電話同時連線到 USB 上的電腦和藍牙總線,則每個總線都會列舉該總線上的子傳輸開發節點,以代表裝置的實體連線。
在此情況下,如果您在 ulFlags 中設定CM_GETIDLIST_FILTER_TRANSPORTRELATIONS旗標,並在 pszFilter 中指定行動電話複合開發節點的裝置實例識別元,則函式會傳回 Buffer 參數中兩個傳輸開發節點的裝置實例識別碼。
如需裝置實例標識碼的詳細資訊,請參閱 裝置標識碼。
注意
cfgmgr32.h 標頭會將CM_Get_Device_ID_List定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼,可能會導致編譯或運行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | 可在 Microsoft Windows 2000 和更新版本的 Windows 中使用。 |
目標平台 | Universal |
標頭 | cfgmgr32.h (包含 Cfgmgr32.h) |
程式庫 | Cfgmgr32.lib |
Dll | CfgMgr32.dll |
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應