CM_Get_Device_Interface_ListW Funktion (cfgmgr32.h)

Artikel
11/20/2024

Die CM_Get_Device_Interface_List-Funktion ruft eine Liste der Geräteschnittstelleninstanzen ab, die zu einer angegebenen Geräteschnittstellenklassegehören.

Syntax

CMAPI CONFIGRET CM_Get_Device_Interface_ListW(
  [in]           LPGUID      InterfaceClassGuid,
  [in, optional] DEVINSTID_W pDeviceID,
  [out]          PZZWSTR     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 MIT NULL beendete Zeichenfolge, die eine Geräteinstanz-IDdarstellt. 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 leere Zeichenfolge zeigt, ruft die Funktion alle Schnittstellen ab, die zur angegebenen Klasse gehören.

[out] Buffer

Vom Aufrufer bereitgestellter Zeiger auf einen Puffer, der mehrere mit NULL beendete Unicode-Zeichenfolgen empfängt, die jeweils den symbolischen Verknüpfungsnamen einer Schnittstelleninstanz darstellen.

[in] BufferLen

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

[in] ulFlags

Enthält eines der folgenden vom Aufrufer bereitgestellten Flags:

CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES

Die Funktion stellt eine Liste bereit, die Geräteschnittstellen enthält, die allen Geräten zugeordnet sind, die der angegebenen GUID- und Geräteinstanz-ID entsprechen, sofern vorhanden.

CM_GET_DEVICE_INTERFACE_LIST_PRESENT

Die Funktion stellt eine Liste bereit, die Geräteschnittstellen enthält, die geräten zugeordnet sind, die derzeit aktiv sind und mit der angegebenen GUID- und Geräteinstanz-ID übereinstimmen, sofern vorhanden.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt die Funktion CR_SUCCESS zurück. Andernfalls wird eine der Fehlercodes mit dem präfix CR_ zurückgegeben, wie in Cfgmgr32.hdefiniert.

Die folgende Tabelle enthält einige der gängigeren Fehlercodes, die diese Funktion möglicherweise zurückgeben kann.

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

Bemerkungen

Zwischen dem Aufrufen 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, wodurch die zurückgegebene Größe nicht mehr gültig ist. Anrufer sollten robust zu dieser Bedingung sein und versuchen, die Größe und die Liste erneut abzurufen, wenn CM_Get_Device_Interface_ListCR_BUFFER_SMALLzurückgibt.

Beispiele

Dieser Codeausschnitt veranschaulicht, wie im Abschnitt "Hinweise" beschrieben, die Größe und die Liste erneut zu erhalten.

    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;
    }

Anmerkung

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
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

Siehe auch

CM_Get_Device_Interface_List_Size

Freigeben über