CM_Get_Device_Interface_ListA-Funktion (cfgmgr32.h)

Die funktion CM_Get_Device_Interface_List ruft eine Liste der Geräteschnittstelleninstanzen ab, die zu einer angegebenen Geräteschnittstellenklasse gehören.

Syntax

CMAPI CONFIGRET CM_Get_Device_Interface_ListA(
  [in]           LPGUID      InterfaceClassGuid,
  [in, optional] DEVINSTID_A pDeviceID,
  [out]          PZZSTR      Buffer,
  [in]           ULONG       BufferLen,
  [in]           ULONG       ulFlags
);

Parameter

[in] InterfaceClassGuid

Stellt eine GUID bereit, die eine Geräteschnittstellenklasse identifiziert.

[in, optional] pDeviceID

Vom Aufrufer bereitgestellter Zeiger auf eine NULL-endende Zeichenfolge, die ein Gerät instance-ID darstellt. Wenn angegeben, ruft die Funktion Geräteschnittstellen ab, die vom Gerät für die angegebene Klasse unterstützt werden. Wenn dieser Wert NULL ist oder auf eine Zeichenfolge der Länge Null zeigt, ruft die Funktion alle Schnittstellen ab, die zur angegebenen Klasse gehören.

[out] Buffer

Vom Aufrufer bereitgestellter Zeiger auf einen Puffer, der mehrere unicode-Zeichenfolgen mit NULL-Termin empfängt, die jeweils den symbolischen Linknamen einer Schnittstelle instance.

[in] BufferLen

Vom Aufrufer bereitgestellter Wert, der die Länge des Puffers in Zeichen angibt, auf den buffer verweist. Rufen Sie CM_Get_Device_Interface_List_Size auf, um die erforderliche Puffergröße zu bestimmen.

[in] ulFlags

Enthält eines der folgenden vom Aufrufer bereitgestellten Flags:

CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES

Die -Funktion stellt eine Liste mit Geräteschnittstellen bereit, die allen Geräten zugeordnet sind, die der angegebenen GUID und der gerätespezifischen instance-ID (sofern vorhanden) entsprechen.

CM_GET_DEVICE_INTERFACE_LIST_PRESENT

Die Funktion stellt eine Liste mit Geräteschnittstellen bereit, die Geräten zugeordnet sind, die derzeit aktiv sind und der angegebenen GUID und gerätespezifischen instance-ID entsprechen, falls vorhanden.

Rückgabewert

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

Die folgende Tabelle enthält einige der häufigeren Fehlercodes, die diese Funktion möglicherweise zurückgibt.

Rückgabecode	Beschreibung
CR_BUFFER_SMALL	Der Pufferpuffer ist zu klein, um die angeforderte Liste der Geräteschnittstellen zu speichern.

Hinweise

Zwischen dem Aufruf CM_Get_Device_Interface_List_Size zum Abrufen der Größe der Liste und dem Aufrufen von CM_Get_Device_Interface_List zum Abrufen der Liste kann dem System eine neue Geräteschnittstelle hinzugefügt werden, die dazu führt, dass die zurückgegebene Größe nicht mehr gültig ist.  Aufrufer sollten gegenüber dieser Bedingung robust sein und versuchen, die Größe und die Liste abzurufen, wenn CM_Get_Device_Interface_ListCR_BUFFER_SMALL zurückgibt.

Beispiele

Dieser Codeausschnitt veranschaulicht das Abrufen der Größe und der Liste, wie im Abschnitt "Hinweise" beschrieben.

    CONFIGRET cr = CR_SUCCESS;
    PWSTR DeviceInterfaceList = NULL;
    ULONG DeviceInterfaceListLength = 0;

    do {
        cr = CM_Get_Device_Interface_List_Size(&DeviceInterfaceListLength,
                                               (LPGUID)&GUID_DEVINTERFACE_VOLUME,
                                               NULL,
                                               CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES);

        if (cr != CR_SUCCESS)
        {
            break;
        }

        if (DeviceInterfaceList != NULL) {
            HeapFree(GetProcessHeap(),
                     0,
                     DeviceInterfaceList);
        }

        DeviceInterfaceList = (PWSTR)HeapAlloc(GetProcessHeap(),
                                               HEAP_ZERO_MEMORY,
                                               DeviceInterfaceListLength * sizeof(WCHAR));

        if (DeviceInterfaceList == NULL)
        {
            cr = CR_OUT_OF_MEMORY;
            break;
        }

        cr = CM_Get_Device_Interface_List((LPGUID)&GUID_DEVINTERFACE_VOLUME,
                                          NULL,
                                          DeviceInterfaceList,
                                          DeviceInterfaceListLength,
                                          CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES);
    } while (cr == CR_BUFFER_SMALL);

    if (cr != CR_SUCCESS)
    {
        goto Exit;
    }

Hinweis

Der cfgmgr32.h-Header definiert CM_Get_Device_Interface_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_Interface_List_Size