CM_Get_Device_ID_ListW Funktion (cfgmgr32.h)
Die CM_Get_Device_ID_List-Funktion ruft eine Liste der Geräteinstanz-IDs für die Geräteinstanzen des lokalen Computersab.
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 der Geräteinstanzbezeichner (IDs) des Computers oder auf NULL-festgelegt ist. Siehe die folgende Beschreibung von ulFlags.
[out] Buffer
Adresse eines Puffers, der einen Satz von Zeichenfolgen der NULL-beendeten Geräteinstanzbezeichner empfängt. Das Ende des Satzes wird durch eine zusätzliche NULL-beendet. Die erforderliche Puffergröße sollte durch Aufrufen von CM_Get_Device_ID_List_Sizeabgerufen werden.
[in] BufferLen
Vom Aufrufer bereitgestellte Länge des durch Bufferangegebenen Puffer in Zeichen.
[in] ulFlags
Eines der folgenden vom Aufrufer bereitgestellten Bit-Flags, die Suchfilter angibt:
CM_GETIDLIST_FILTER_BUSRELATIONS
Wenn dieses Flag festgelegt ist, muss pszFilter- einen Geräteinstanzbezeichner angeben. Die Funktion gibt Geräteinstanz-IDs für die Busbeziehungen der angegebenen Geräteinstanz 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ätesetupklasse GUID angibt. Die zurückgegebene Liste enthält Geräteinstanzen, für die die Eigenschaft (auf die durch die CM_DRP_CLASSGUID Konstante verwiesen wird) mit der angegebenen GuiD der Geräteeinrichtungsklasse übereinstimmt.
Die CM_DRP_CLASSGUID Konstante wird in Cfgmgr32.hdefiniert.
CM_GETIDLIST_FILTER_PRESENT (Windows 7 und höhere Versionen von Windows)
Wenn dieses Kennzeichen festgelegt ist, enthält die zurückgegebene Liste nur Geräteinstanzen, die derzeit im System vorhanden sind. Dieser Wert kann mit anderen ulFlags- Werten kombiniert werden, z. B. CM_GETIDLIST_FILTER_CLASS.
CM_GETIDLIST_FILTER_TRANSPORTRELATIONS (Windows 7 und höhere Versionen von Windows)
Wenn dieses Flag festgelegt ist, muss pszFilter den Geräteinstanzbezeichner eines zusammengesetzten Geräteknotens angeben (devnode).
Die Funktion gibt die Geräteinstanzbezeichner 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 für 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äteinstanzbezeichner angeben. Die Funktion gibt Geräteinstanz-IDs für die Ejection Relations der angegebenen Geräteinstanz zurück.
CM_GETIDLIST_FILTER_ENUMERATOR
Wenn dieses Kennzeichen 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 Enumerationsnamen bereitstellt, gibt die Funktion Geräteinstanz-IDs für die Instanzen der einzelnen Geräte zurück, die dem Enumerator zugeordnet sind. Enumeratornamen können durch Aufrufen von CM_Enumerate_Enumeratorsabgerufen werden.
Wenn pszFilter sowohl einen Enumerator als auch eine Geräte-IDbereitstellt, gibt die Funktion Geräteinstanz-IDs nur für die Instanzen des angegebenen Geräts zurück, das dem Enumerator zugeordnet ist.
CM_GETIDLIST_FILTER_NONE
Wenn dieses Kennzeichen festgelegt ist, wird pszFilter- ignoriert, und eine Liste aller Geräte auf dem System wird zurückgegeben.
CM_GETIDLIST_FILTER_POWERRELATIONS
Wenn dieses Flag festgelegt ist, muss pszFilter- einen Geräteinstanzbezeichner angeben. Die Funktion gibt Geräteinstanz-IDs für die Leistungsbeziehungen der angegebenen Geräteinstanz zurück.
CM_GETIDLIST_FILTER_REMOVALRELATIONS
Wenn dieses Flag festgelegt ist, muss pszFilter- einen Geräteinstanzbezeichner angeben. Die Funktion gibt Geräteinstanz-IDs für die Entfernungsbeziehungen der angegebenen Geräteinstanz zurück.
CM_GETIDLIST_FILTER_SERVICE
Wenn dieses Kennzeichen festgelegt ist, muss pszFilter- den Namen eines Microsoft Windows-Diensts (in der Regel ein Treiber) angeben. Die Funktion gibt Geräteinstanz-IDs für die Geräteinstanzen zurück, die vom angegebenen Dienst gesteuert werden.
Beachten Sie, dass diese Funktion standardmäßig erstellt wird, wenn die Gerätestruktur keine devnode für den angegebenen Dienst enthält. Um dieses Verhalten zu verhindern, legen Sie auch CM_GETIDLIST_DONOTGENERATE fest.
Wenn kein Suchfilterflagge angegeben ist, gibt die Funktion alle Geräteinstanz-IDs für alle Geräteinstanzen zurück.
Rückgabewert
Wenn der Vorgang erfolgreich ist, gibt die Funktion CR_SUCCESS zurück. Andernfalls wird eine der CR_-präfixierten Fehlercodes zurückgegeben, die in Cfgmgr32.hdefiniert sind.
Bemerkungen
Ab Windows 7 wird ein Gerät, das mehrere Transportpfade für paketbasierte Daten unterstützt, als zusammengesetztes Gerät bezeichnet und durch eine zusammengesetzte Devnode-dargestellt. Ein zusammengesetzter Devnode stellt das zusammengesetzte Gerät für den Benutzer und die Anwendungen als einzelnes Gerät logisch dar, obwohl der zusammengesetzte Devnode mehrere Pfade zum physischen Gerät haben kann.
Jeder aktive Transportpfad zum physischen Gerät wird durch einen Transport devnode dargestellt und wird 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 eine 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-Devnode 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äteinstanz-ID der zusammengesetzten Devnode des Mobiltelefons in pszFilter-angeben, gibt die Funktion die Geräteinstanz-IDs für die beiden Transport devnodes im Buffer Parameter zurück.
Weitere Informationen zu Geräteinstanz-IDs finden Sie unter Device Identification Strings.
Anmerkung
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 |
|---|---|
| mindestens unterstützte Client- | Verfügbar in Microsoft Windows 2000 und höheren Versionen von Windows. |
| Zielplattform- | Universal |
| Header- | cfgmgr32.h (enthalten Cfgmgr32.h) |
| Library | Cfgmgr32.lib |
| DLL- | CfgMgr32.dll |