función CM_Get_Device_ID_ListA (cfgmgr32.h)

La función CM_Get_Device_ID_List recupera una lista de identificadores de instancia de dispositivo para las instancias de dispositivo del equipo local.

Sintaxis

CMAPI CONFIGRET CM_Get_Device_ID_ListA(
  [in, optional] PCSTR  pszFilter,
  [out]          PZZSTR Buffer,
  [in]           ULONG  BufferLen,
  [in]           ULONG  ulFlags
);

Parámetros

[in, optional] pszFilter

Puntero proporcionado por el autor de la llamada a una cadena de caracteres que se establece en un subconjunto de identificadores de instancia de dispositivo (identificadores) del equipo o en NULL. Consulte la siguiente descripción de ulFlags.

[out] Buffer

Dirección de un búfer para recibir un conjunto de cadenas de identificador de instancia de dispositivo terminadas en NULL. El final del conjunto finaliza con un valor NULL adicional. El tamaño de búfer necesario debe obtenerse llamando a CM_Get_Device_ID_List_Size.

[in] BufferLen

Longitud proporcionada por el autor de la llamada, en caracteres, del búfer especificado por Buffer.

[in] ulFlags

Una de las siguientes marcas de bits proporcionadas por el autor de la llamada que especifica filtros de búsqueda:

CM_GETIDLIST_FILTER_BUSRELATIONS

Si se establece esta marca, pszFilter debe especificar un identificador de instancia de dispositivo. La función devuelve identificadores de instancia de dispositivo para las relaciones de bus de la instancia de dispositivo especificada.

CM_GETIDLIST_FILTER_CLASS (Windows 7 y versiones posteriores de Windows)

Si se establece esta marca, pszFilter contiene una cadena que especifica un GUID de clase de instalación de dispositivo . La lista devuelta contiene instancias de dispositivo para las que la propiedad (a la que hace referencia la constante CM_DRP_CLASSGUID) coincide con el GUID de la clase de instalación de dispositivo especificada.

La constante CM_DRP_CLASSGUID se define en Cfgmgr32.h.

CM_GETIDLIST_FILTER_PRESENT (Windows 7 y versiones posteriores de Windows)

Si se establece esta marca, la lista devuelta contiene solo instancias de dispositivo que están presentes actualmente en el sistema. Este valor se puede combinar con otros valores ulFlags , como CM_GETIDLIST_FILTER_CLASS.

CM_GETIDLIST_FILTER_TRANSPORTRELATIONS (Windows 7 y versiones posteriores de Windows)

Si se establece esta marca, pszFilter debe especificar el identificador de instancia de dispositivo de un nodo de dispositivo compuesto (devnode).

La función devuelve los identificadores de instancia de dispositivo de los devnodes que representan las relaciones de transporte del nodo compuesto especificado.

Para obtener más información sobre los devnodes compuestos y las relaciones de transporte, vea la siguiente sección Comentarios .

CM_GETIDLIST_DONOTGENERATE

Solo se usa con CM_GETIDLIST_FILTER_SERVICE. Si se establece y si el árbol de dispositivos no contiene un devnode para el servicio especificado, esta marca impide que la función cree un devnode para el servicio.

CM_GETIDLIST_FILTER_EJECTRELATIONS

Si se establece esta marca, pszFilter debe especificar un identificador de instancia de dispositivo. La función devuelve identificadores de instancia de dispositivo para las relaciones de ejección de la instancia de dispositivo especificada.

CM_GETIDLIST_FILTER_ENUMERATOR

Si se establece esta marca, pszFilter debe especificar el nombre de un enumerador de dispositivos, seguido opcionalmente de un identificador de dispositivo. El formato de cadena es EnumeratorName\<DeviceID>, como ROOT o ROOT\*PNP0500.

Si pszFilter proporciona solo un nombre de enumerador, la función devuelve identificadores de instancia de dispositivo para las instancias de cada dispositivo asociado al enumerador. Los nombres del enumerador se pueden obtener llamando a CM_Enumerate_Enumerators.

Si pszFilter proporciona un enumerador y un identificador de dispositivo, la función devuelve identificadores de instancia de dispositivo solo para las instancias del dispositivo especificado que está asociada al enumerador.

CM_GETIDLIST_FILTER_NONE

Si se establece esta marca, se omite pszFilter y se devuelve una lista de todos los dispositivos del sistema.

CM_GETIDLIST_FILTER_POWERRELATIONS

Si se establece esta marca, pszFilter debe especificar un identificador de instancia de dispositivo. La función devuelve los identificadores de instancia de dispositivo para las relaciones de potencia de la instancia de dispositivo especificada.

CM_GETIDLIST_FILTER_REMOVALRELATIONS

Si se establece esta marca, pszFilter debe especificar un identificador de instancia de dispositivo. La función devuelve identificadores de instancia de dispositivo para las relaciones de eliminación de la instancia de dispositivo especificada.

CM_GETIDLIST_FILTER_SERVICE

Si se establece esta marca, pszFilter debe especificar el nombre de un servicio de Microsoft Windows (normalmente un controlador). La función devuelve identificadores de instancia de dispositivo para las instancias de dispositivo controladas por el servicio especificado.

Tenga en cuenta que si el árbol de dispositivos no contiene un devnode para el servicio especificado, esta función crea una de forma predeterminada. Para impedir este comportamiento, establezca también CM_GETIDLIST_DONOTGENERATE.

Si no se especifica ninguna marca de filtro de búsqueda, la función devuelve todos los identificadores de instancia de dispositivo para todas las instancias de dispositivo.

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 CR_ prefijo definidos en Cfgmgr32.h.

Comentarios

A partir de Windows 7, un dispositivo que admite varias rutas de transporte para datos basados en paquetes se conoce como un dispositivo compuesto y se representa mediante un devnodecompuesto. Un nodo devnode compuesto representa lógicamente el dispositivo compuesto para el usuario y las aplicaciones como un único dispositivo, aunque el devnode compuesto pueda tener varias rutas de acceso al dispositivo físico.

Cada ruta de transporte activa al dispositivo físico se representa mediante un devnode de transporte y se conoce como una relación de transporte para el dispositivo compuesto.

El devnode compuesto (pero no los devnodes de transporte relacionados) expone las interfaces de dispositivo a las aplicaciones y al sistema. Cuando una aplicación usa estas interfaces de dispositivo público, el dispositivo compuesto enruta los datos basados en paquetes a uno o varios de estos devnodes de transporte, que luego transporta los datos al dispositivo físico.

Por ejemplo, si un teléfono móvil físico está conectado simultáneamente al equipo en el USB y los autobuses Bluetooth, cada bus enumera un nodo de desarrollo de transporte secundario en ese bus para representar la conexión física del dispositivo.

En este caso, si establece las marcas de CM_GETIDLIST_FILTER_TRANSPORTRELATIONS en ulFlags y especifica el identificador de instancia de dispositivo del devnode compuesto del teléfono celular en pszFilter, la función devuelve los identificadores de instancia de dispositivo para los dos devnodes de transporte en el parámetro Buffer .

Para obtener más información sobre los identificadores de instancia de dispositivo, consulte Cadenas de identificación de dispositivos.

Nota

El encabezado cfgmgr32.h define CM_Get_Device_ID_List como 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_ID_List_Size