función CM_Get_Device_Interface_ListW (cfgmgr32.h)

  • Artículo

La función CM_Get_Device_Interface_List recupera una lista de instancias de interfaz de dispositivo que pertenecen a una clase de interfaz de dispositivo especificada.

Sintaxis

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

Parámetros

[in] InterfaceClassGuid

Proporciona un GUID que identifica una clase de interfaz de dispositivo.

[in, optional] pDeviceID

Puntero proporcionado por el autor de la llamada a una cadena terminada en NULL que representa un identificador de instancia de dispositivo. Si se especifica, la función recupera interfaces de dispositivo compatibles con el dispositivo para la clase especificada. Si este valor es NULL o si apunta a una cadena de longitud cero, la función recupera todas las interfaces que pertenecen a la clase especificada.

[out] Buffer

Puntero proporcionado por el autor de la llamada a un búfer que recibe varias cadenas Unicode terminadas en NULL, cada una que representa el nombre de vínculo simbólico de una instancia de interfaz.

[in] BufferLen

Valor proporcionado por el autor de la llamada que especifica la longitud, en caracteres, del búfer al que apunta Buffer. Llame a CM_Get_Device_Interface_List_Size para determinar el tamaño de búfer necesario.

[in] ulFlags

Contiene una de las siguientes marcas proporcionadas por el autor de la llamada:

CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES

La función proporciona una lista que contiene interfaces de dispositivo asociadas a todos los dispositivos que coinciden con el GUID y el identificador de instancia de dispositivo especificados, si los hay.

CM_GET_DEVICE_INTERFACE_LIST_PRESENT

La función proporciona una lista que contiene interfaces de dispositivo asociadas a los dispositivos que están actualmente activos y que coinciden con el GUID y el identificador de instancia de dispositivo especificados, si los hay.

Valor devuelto

Si la operación se realiza correctamente, la función devuelve CR_SUCCESS. De lo contrario, devuelve uno de los códigos de error con el prefijo CR_ tal y como se define en Cfgmgr32.h.

En la tabla siguiente se incluyen algunos de los códigos de error más comunes que puede devolver esta función.

Código devuelto Descripción
CR_BUFFER_SMALL
 El búfer de búfer es demasiado pequeño para contener la lista solicitada de interfaces de dispositivo.

Comentarios

Entre llamar a CM_Get_Device_Interface_List_Size obtener el tamaño de la lista y llamar a CM_Get_Device_Interface_List para obtener la lista, se puede agregar una nueva interfaz de dispositivo al sistema, lo que hace que el tamaño devuelto ya no sea válido.  Los autores de llamadas deben ser sólidos para esa condición y volver a intentar obtener el tamaño y la lista si CM_Get_Device_Interface_List devuelve CR_BUFFER_SMALL.

Ejemplos

En este fragmento de código se muestra cómo volver a intentar obtener el tamaño y la lista, tal y como se describe en la sección Comentarios.

    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

El encabezado cfgmgr32.h define CM_Get_Device_Interface_List como un alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito Value
Cliente mínimo compatible Disponible en Microsoft Windows 2000 y versiones posteriores de Windows.
Plataforma de destino Universal
Encabezado cfgmgr32.h (incluya Cfgmgr32.h)
Library Cfgmgr32.lib
Archivo DLL CfgMgr32.dll

Consulte también

CM_Get_Device_Interface_List_Size