CM_Get_Device_ID_ListA函式 (cfgmgr32.h)

發行項
02/23/2024

CM_Get_Device_ID_List函式會擷取本機電腦裝置實例的裝置實例標識碼清單。

語法

CMAPI CONFIGRET CM_Get_Device_ID_ListA(
  [in, optional] PCSTR  pszFilter,
  [out]          PZZSTR 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

另請參閱

CM_Get_Device_ID_List_Size

共用方式為