Función SetupDiCreateDeviceInfoW (setupapi.h)

Artículo
03/15/2023

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 SetupDiCreateDeviceInfoW(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PCWSTR           DeviceName,
  [in]            const GUID       *ClassGuid,
  [in, optional]  PCWSTR           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 por raíz sin el prefijo del enumerador y el sufijo del identificador de instancia (por ejemplo, "*PNP0500"). El identificador de dispositivo enumerado en raíz solo se puede usar si la marca DICD_GENERATE_ID se especifica en el parámetro CreationFlags .

[in] ClassGuid

Puntero al GUID de clase de configuración del dispositivo para el 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 puede ser NULL.

[in, optional] hwndParent

Identificador de la ventana de nivel superior que se usará para cualquier interfaz de usuario relacionada con la instalación del dispositivo. Este identificador es opcional y puede ser 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 solo contiene un identificador de dispositivo enumerado por 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 puede ser NULL. Si se proporciona la estructura, el autor de la llamada debe establecer el miembro cbSize de esta estructura en sizeof(SP_DEVINFO_DATA) antes de llamar a la función . Para obtener más información, vea la siguiente sección Comentarios .

Valor devuelto

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

Comentarios

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

Si esta instancia de dispositivo se agrega 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 se produce si no se establece la marca DICD_GENERATE_ID.

Si el nuevo elemento de información del dispositivo se creó correctamente, pero el búfer DeviceInfoData proporcionado por el autor de la llamada 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.

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 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	Escritorio
Encabezado	setupapi.h (incluya Setupapi.h)
Library	Setupapi.lib