Función SetupDiCreateDeviceInfoA (setupapi.h)

Artículo
11/20/2024

La función SetupDiCreateDeviceInfo crea un nuevo elemento de información del dispositivo y lo agrega como un nuevo miembro al conjunto de información del dispositivo especificado.

Sintaxis

WINSETUPAPI BOOL SetupDiCreateDeviceInfoA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PCSTR            DeviceName,
  [in]            const GUID       *ClassGuid,
  [in, optional]  PCSTR            DeviceDescription,
  [in, optional]  HWND             hwndParent,
  [in]            DWORD            CreationFlags,
  [out, optional] PSP_DEVINFO_DATA DeviceInfoData
);

Parámetros

[in] DeviceInfoSet

Identificador del conjunto de información del dispositivo para el equipo local.

[in] DeviceName

Puntero a una cadena terminada en NULL que proporciona un identificador de instancia de dispositivo completo (por ejemplo, "Root*PNP0500\0000") o un identificador de dispositivo enumerado en raíz sin el prefijo del enumerador y el sufijo de identificador de instancia (por ejemplo, "*PNP0500"). El identificador de dispositivo enumerado en raíz solo se puede usar si se especifica la marca DICD_GENERATE_ID en el parámetro CreationFlags.

[in] ClassGuid

Puntero a la clase de configuración de dispositivo GUID del dispositivo. Si no se conoce la clase de configuración del dispositivo, establezca *ClassGuid en una estructura de GUID_NULL.

[in, optional] DeviceDescription

Puntero a una cadena terminada en NULL que proporciona la descripción de texto del dispositivo. Este puntero es opcional y se puede NULL.

[in, optional] hwndParent

Identificador de la ventana de nivel superior que se va a usar para cualquier interfaz de usuario relacionada con la instalación del dispositivo. Este identificador es opcional y se puede NULL.

[in] CreationFlags

Variable de tipo DWORD que controla cómo se crea el elemento de información del dispositivo. Puede ser una combinación de los valores siguientes:

DICD_GENERATE_ID

Si se especifica esta marca, deviceName contiene solo un identificador de dispositivo enumerado en raíz y el sistema usa ese identificador para generar un identificador de instancia de dispositivo completo para el nuevo elemento de información del dispositivo.

Llame a setupDiGetDeviceInstanceId para recuperar el identificador de instancia de dispositivo que se generó para este elemento de información del dispositivo.

DICD_INHERIT_CLASSDRVS

Si se especifica esta marca, el elemento de información del dispositivo resultante hereda la lista de controladores de clase, si existe, asociada al conjunto de información del dispositivo. Además, si hay un controlador seleccionado para el conjunto de información del dispositivo, ese mismo controlador se selecciona para el nuevo elemento de información del dispositivo.

[out, optional] DeviceInfoData

Puntero a una estructura SP_DEVINFO_DATA que recibe el nuevo elemento de información del dispositivo. Este puntero es opcional y se puede NULL. Si se proporciona la estructura, el autor de la llamada debe establecer el cbSize miembro de esta estructura en sizeof(SP_DEVINFO_DATA) antes de llamar a la función. Para obtener más información, consulte la siguiente sección Comentarios.

Valor devuelto

La función devuelve TRUE si se ejecuta correctamente. De lo contrario, devuelve FALSE y se puede recuperar el error registrado realizando una llamada a GetLastError.

Observaciones

El autor de la llamada de esta función debe ser miembro del grupo Administradores.

Si se agrega esta instancia de dispositivo a un conjunto que tiene una clase asociada, la clase de dispositivo debe ser la misma o se produce un error en la llamada. En este caso, una llamada a GetLastError devuelve ERROR_CLASS_MISMATCH.

Si la instancia de dispositivo especificada es la misma que una clave de instancia de dispositivo existente en el Registro, se produce un error en la llamada. En este caso, una llamada a GetLastError devuelve ERROR_DEVINST_ALREADY_EXISTS. Esto solo ocurre si no se establece la marca DICD_GENERATE_ID.

Si el nuevo elemento de información del dispositivo se creó correctamente, pero el deviceInfoData proporcionado por el autor de la llamada búfer no es válido, la función devuelve FALSE. En este caso, una llamada a GetLastError devuelve ERROR_INVALID_USER_BUFFER. Sin embargo, el elemento de información del dispositivo se habrá agregado como un nuevo miembro del conjunto ya.

El DeviceInfoSet solo debe contener elementos en el equipo local.

Nota

El encabezado setupapi.h define SetupDiCreateDeviceInfo 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Disponible en Microsoft Windows 2000 y versiones posteriores de Windows.
de la plataforma de destino de	Escritorio
encabezado de	setupapi.h (incluya Setupapi.h)
biblioteca de	Setupapi.lib