CM_Get_Device_ID_ListW-Funktion (cfgmgr32.h)

Die CM_Get_Device_ID_List-Funktion ruft eine Liste der Geräte-instance-IDs für die Geräteinstanzen des lokalen Computers ab.

Syntax

CMAPI CONFIGRET CM_Get_Device_ID_ListW(
  [in, optional] PCWSTR  pszFilter,
  [out]          PZZWSTR Buffer,
  [in]           ULONG   BufferLen,
  [in]           ULONG   ulFlags
);

Parameter

[in, optional] pszFilter

Vom Aufrufer bereitgestellter Zeiger auf eine Zeichenfolge, die entweder auf eine Teilmenge des Geräts des Computers instance IDs (Identifiers) oder auf NULL festgelegt ist. Siehe die folgende Beschreibung von ulFlags.

[out] Buffer

Adresse eines Puffers, um einen Satz von NULL-beendeten Geräte instance Bezeichnerzeichenfolgen zu empfangen. Das Ende der Gruppe wird durch einen zusätzlichen NULL-Wert beendet. Die erforderliche Puffergröße sollte durch Aufrufen CM_Get_Device_ID_List_Size abgerufen werden.

[in] BufferLen

Vom Aufrufer angegebene Länge des puffers in Zeichen.

[in] ulFlags

Eines der folgenden vom Aufrufer bereitgestellten Bitflags, das Suchfilter angibt:

CM_GETIDLIST_FILTER_BUSRELATIONS

Wenn dieses Flag festgelegt ist, muss pszFilter ein Gerät instance-Bezeichner angeben. Die Funktion gibt Geräte-instance-IDs für die Busbeziehungen des angegebenen Gerätes instance zurück.

CM_GETIDLIST_FILTER_CLASS (Windows 7 und höhere Versionen von Windows)

Wenn dieses Flag festgelegt ist, enthält pszFilter eine Zeichenfolge, die eine Geräteeinrichtungsklasse-GUID angibt. Die zurückgegebene Liste enthält Geräteinstanzen, für die die -Eigenschaft (auf die von der CM_DRP_CLASSGUID-Konstante verwiesen wird) mit der angegebenen Gerätesetupklasse GUID übereinstimmt.

Die CM_DRP_CLASSGUID Konstante wird in Cfgmgr32.h definiert.

CM_GETIDLIST_FILTER_PRESENT (Windows 7 und höhere Versionen von Windows)

Wenn dieses Flag festgelegt ist, enthält die zurückgegebene Liste nur Geräteinstanzen, die derzeit im System vorhanden sind. Dieser Wert kann mit anderen ulFlags-Werten wie CM_GETIDLIST_FILTER_CLASS kombiniert werden.

CM_GETIDLIST_FILTER_TRANSPORTRELATIONS (Windows 7 und höhere Versionen von Windows)

Wenn dieses Flag festgelegt ist, muss pszFilter das Gerät instance Bezeichner eines zusammengesetzten Geräteknotens (devnode) angeben.

Die Funktion gibt das Gerät instance Bezeichner der Devnodes zurück, die die Transportbeziehungen des angegebenen zusammengesetzten Devnodes darstellen.

Weitere Informationen zu zusammengesetzten Devnodes und Transportbeziehungen finden Sie im folgenden Abschnitt Hinweise .

CM_GETIDLIST_DONOTGENERATE

Wird nur mit CM_GETIDLIST_FILTER_SERVICE verwendet. Wenn festgelegt ist und die Gerätestruktur keinen Devnode für den angegebenen Dienst enthält, verhindert dieses Flag, dass die Funktion einen Devnode für den Dienst erstellt.

CM_GETIDLIST_FILTER_EJECTRELATIONS

Wenn dieses Flag festgelegt ist, muss pszFilter ein Gerät instance-Bezeichner angeben. Die Funktion gibt Geräte-instance-IDs für die Auswurfbeziehungen des angegebenen Gerätes instance zurück.

CM_GETIDLIST_FILTER_ENUMERATOR

Wenn dieses Flag festgelegt ist, muss pszFilter den Namen eines Geräteenumerators angeben, optional gefolgt von einer Geräte-ID. Das Zeichenfolgenformat ist EnumeratorName\<DeviceID>, z. B. ROOT oder ROOT\*PNP0500.

Wenn pszFilter nur einen Enumeratornamen bereitstellt, gibt die Funktion Geräte-instance-IDs für die Instanzen jedes Geräts zurück, das dem Enumerator zugeordnet ist. Enumeratornamen können durch Aufrufen von CM_Enumerate_Enumerators abgerufen werden.

Wenn pszFilter sowohl einen Enumerator als auch eine Geräte-ID bereitstellt, gibt die Funktion Geräte-instance-IDs nur für die Instanzen des angegebenen Geräts zurück, das dem Enumerator zugeordnet ist.

CM_GETIDLIST_FILTER_NONE

Wenn dieses Flag festgelegt ist, wird pszFilter ignoriert, und eine Liste aller Geräte im System wird zurückgegeben.

CM_GETIDLIST_FILTER_POWERRELATIONS

Wenn dieses Flag festgelegt ist, muss pszFilter ein Gerät instance-Bezeichner angeben. Die Funktion gibt Geräte-instance-IDs für die Leistungsbeziehungen des angegebenen Gerätes instance zurück.

CM_GETIDLIST_FILTER_REMOVALRELATIONS

Wenn dieses Flag festgelegt ist, muss pszFilter ein Gerät instance-Bezeichner angeben. Die Funktion gibt Geräte-instance-IDs für die Entfernungsbeziehungen des angegebenen Gerätes instance zurück.

CM_GETIDLIST_FILTER_SERVICE

Wenn dieses Flag festgelegt ist, muss pszFilter den Namen eines Microsoft Windows-Diensts (in der Regel einen Treiber) angeben. Die Funktion gibt Geräte-instance-IDs für die Geräteinstanzen zurück, die vom angegebenen Dienst gesteuert werden.

Beachten Sie, dass diese Funktion standardmäßig einen Devnode erstellt, wenn die Gerätestruktur keinen Devnode für den angegebenen Dienst enthält. Um dieses Verhalten zu verhindern, legen Sie auch CM_GETIDLIST_DONOTGENERATE fest.

Wenn kein Suchfilterflag angegeben ist, gibt die Funktion alle Geräte-instance-IDs für alle Geräteinstanzen zurück.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt die Funktion CR_SUCCESS zurück. Andernfalls wird einer der CR_-Präfix-Fehlercodes zurückgegeben, die in Cfgmgr32.h definiert sind.

Hinweise

Ab Windows 7 wird ein Gerät, das mehrere Transportpfade für paketbasierte Daten unterstützt, als zusammengesetztes Gerät bezeichnet und durch einen zusammengesetzten Devnode dargestellt. Ein zusammengesetzter Devnode stellt das zusammengesetzte Gerät für den Benutzer und die Anwendungen logisch als einzelnes Gerät dar, auch wenn der zusammengesetzte Devnode mehrere Pfade zum physischen Gerät haben kann.

Jeder aktive Transportpfad zum physischen Gerät wird durch einen Transportentwicklungsknoten dargestellt und als Transportbeziehung für das zusammengesetzte Gerät bezeichnet.

Der zusammengesetzte Devnode (aber nicht die zugehörigen Transportentwicklungsknoten) macht Geräteschnittstellen für Anwendungen und das System verfügbar. Wenn eine Anwendung diese öffentlichen Geräteschnittstellen verwendet, leitet das zusammengesetzte Gerät die paketbasierten Daten an einen oder mehrere dieser Transportentwicklungsknoten weiter, die die Daten dann an das physische Gerät übertragen.

Wenn beispielsweise ein physisches Mobiltelefon gleichzeitig mit dem Computer auf dem USB- und den Bluetooth-Bussen verbunden ist, zählt jeder Bus einen untergeordneten Transportentwicklungsknoten auf diesem Bus auf, um die physische Verbindung des Geräts darzustellen.

Wenn Sie in diesem Fall die CM_GETIDLIST_FILTER_TRANSPORTRELATIONS-Flags in ulFlags festlegen und die Geräte-instance-ID des zusammengesetzten Devnodes des Mobiltelefons in pszFilter angeben, gibt die Funktion das Gerät instance IDs für die beiden Transportentwicklungsknoten im Buffer-Parameter zurück.

Weitere Informationen zu Geräte-instance-IDs finden Sie unter Geräteidentifikationszeichenfolgen.

Hinweis

Der cfgmgr32.h-Header definiert CM_Get_Device_ID_List als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Microsoft Windows 2000 und höheren Versionen von Windows.
Zielplattform	Universell
Header	cfgmgr32.h (einschließlich Cfgmgr32.h)
Bibliothek	Cfgmgr32.lib
DLL	CfgMgr32.dll

Weitere Informationen

CM_Get_Device_ID_List_Size