funzione CM_Get_Device_Interface_ListW (cfgmgr32.h)

Articolo
11/20/2024

La funzione CM_Get_Device_Interface_List recupera un elenco di istanze dell'interfaccia del dispositivo che appartengono a una classe di interfaccia del dispositivo specificata.

Sintassi

CMAPI CONFIGRET CM_Get_Device_Interface_ListW(
  [in]           LPGUID      InterfaceClassGuid,
  [in, optional] DEVINSTID_W pDeviceID,
  [out]          PZZWSTR     Buffer,
  [in]           ULONG       BufferLen,
  [in]           ULONG       ulFlags
);

Parametri

[in] InterfaceClassGuid

Fornisce un GUID che identifica una classe di interfaccia del dispositivo.

[in, optional] pDeviceID

Puntatore fornito dal chiamante a una stringa con terminazione NULL che rappresenta un ID istanza del dispositivo . Se specificato, la funzione recupera le interfacce del dispositivo supportate dal dispositivo per la classe specificata. Se questo valore è NULLo se punta a una stringa di lunghezza zero, la funzione recupera tutte le interfacce che appartengono alla classe specificata.

[out] Buffer

Puntatore fornito dal chiamante a un buffer che riceve più stringhe Unicode con terminazione NULL, ognuna che rappresenta il nome di collegamento simbolico di un'istanza dell'interfaccia.

[in] BufferLen

Valore fornito dal chiamante che specifica la lunghezza, in caratteri, del buffer a cui punta Buffer. Chiamare CM_Get_Device_Interface_List_Size per determinare le dimensioni del buffer necessarie.

[in] ulFlags

Contiene uno dei flag forniti dal chiamante seguenti:

CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES

La funzione fornisce un elenco contenente interfacce di dispositivo associate a tutti i dispositivi che corrispondono al GUID e all'ID istanza del dispositivo specificati, se presenti.

CM_GET_DEVICE_INTERFACE_LIST_PRESENT

La funzione fornisce un elenco contenente le interfacce del dispositivo associate ai dispositivi attualmente attivi e che corrispondono al GUID specificato e all'ID istanza del dispositivo, se presente.

Valore restituito

Se l'operazione ha esito positivo, la funzione restituisce CR_SUCCESS. In caso contrario, restituisce uno dei codici di errore con il prefisso CR_ definito in Cfgmgr32.h.

La tabella seguente include alcuni dei codici di errore più comuni che questa funzione potrebbe restituire.

Codice restituito	Descrizione
CR_BUFFER_SMALL	Il buffer buffer buffer è troppo piccolo per contenere l'elenco richiesto di interfacce del dispositivo.

Osservazioni

Tra le chiamate CM_Get_Device_Interface_List_Size per ottenere le dimensioni dell'elenco e la chiamata di CM_Get_Device_Interface_List per ottenere l'elenco, è possibile aggiungere una nuova interfaccia del dispositivo al sistema che causa la restituzione delle dimensioni non più valida. I chiamanti devono essere affidabili per tale condizione e riprovare a ottenere le dimensioni e l'elenco se CM_Get_Device_Interface_List restituisce CR_BUFFER_SMALL.

Esempi

Questo frammento di codice illustra la ripetizione di tentativi di recupero delle dimensioni e dell'elenco, come descritto nella sezione Osservazioni.

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

Nota

L'intestazione cfgmgr32.h definisce CM_Get_Device_Interface_List come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Disponibile in Microsoft Windows 2000 e versioni successive di Windows.
piattaforma di destinazione	Universale
intestazione	cfgmgr32.h (include Cfgmgr32.h)
libreria	Cfgmgr32.lib
dll	CfgMgr32.dll

Vedere anche

CM_Get_Device_Interface_List_Size

Condividi tramite