CM_Get_Device_ID_ListA-Funktion (cfgmgr32.h)

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

Syntax

CMAPI CONFIGRET CM_Get_Device_ID_ListA(
  [in, optional] PCSTR  pszFilter,
  [out]          PZZSTR 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 oder auf NULL festgelegt ist. Weitere Informationen finden Sie in der folgenden Beschreibung von ulFlags.

[out] Buffer

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

[in] BufferLen

Vom Aufrufer bereitgestellte Länge des durch Puffer angegebenen 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 einen Geräte-instance-Bezeichner angeben. Die Funktion gibt Geräte-instance-IDs für die Busbeziehungen des angegebenen Geräte-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 GUID für die Geräteeinrichtungsklasse 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ätesetupklassen-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 den Geräte 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 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 einen Geräte-instance-Bezeichner angeben. Die Funktion gibt Geräte-instance-IDs für die Auswurfbeziehungen des angegebenen gerätespezifischen 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 einen Geräte-instance-Bezeichner angeben. Die Funktion gibt Geräte-instance-IDs für die Leistungsbeziehungen des angegebenen Geräte-instance zurück.

CM_GETIDLIST_FILTER_REMOVALRELATIONS

Wenn dieses Flag festgelegt ist, muss pszFilter einen Geräte-instance-Bezeichner angeben. Die Funktion gibt Geräte-instance-IDs für die Entfernungsbeziehungen des angegebenen Geräte-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.

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

Wenn kein Suchfilterflag angegeben wird, 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 in Cfgmgr32.h definierten Fehlercodes mit CR_ Präfix zurückgegeben.

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 logisch für den Benutzer und die Anwendungen als einzelnes Gerät dar, obwohl der zusammengesetzte Devnode mehrere Pfade zum physischen Gerät aufweisen 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 Transport-Devnodes) 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 Transport-Devnodes weiter, die dann die Daten 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 Transport-Entwicklungsknoten 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 Transport-Devnodes 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 Code, der nicht Codierungsneutral ist, 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 (include Cfgmgr32.h)
Bibliothek Cfgmgr32.lib
DLL CfgMgr32.dll

Weitere Informationen

CM_Get_Device_ID_List_Size