Función SetupDiCreateDevRegKeyA (setupapi.h)

Artículo
03/15/2023

La función SetupDiCreateDevRegKey crea una clave del Registro para la información de configuración específica del dispositivo y devuelve un identificador a la clave.

Sintaxis

WINSETUPAPI HKEY SetupDiCreateDevRegKeyA(
  [in]           HDEVINFO         DeviceInfoSet,
  [in]           PSP_DEVINFO_DATA DeviceInfoData,
  [in]           DWORD            Scope,
  [in]           DWORD            HwProfile,
  [in]           DWORD            KeyType,
  [in, optional] HINF             InfHandle,
  [in, optional] PCSTR            InfSectionName
);

Parámetros

[in] DeviceInfoSet

Identificador de un conjunto de información de dispositivo que contiene un elemento de información del dispositivo que representa el dispositivo para el que se va a crear una clave del Registro.

[in] DeviceInfoData

Puntero a una estructura de SP_DEVINFO_DATA que especifica el elemento de información del dispositivo en DeviceInfoSet.

[in] Scope

Ámbito de la clave del Registro que se va a crear. El ámbito determina dónde se almacena la información. La clave creada puede ser específica del perfil de hardware o global. Puede ser uno de los siguientes valores:

DICS_FLAG_GLOBAL

Cree una clave para almacenar información de configuración global. Esta información no es específica de un perfil de hardware determinado. En los sistemas operativos basados en NT, esto crea una clave que se basa en HKEY_LOCAL_MACHINE. La clave exacta abierta depende del valor del parámetro KeyType .

DICS_FLAG_CONFIGSPECIFIC

Cree una clave para almacenar información de configuración específica del perfil de hardware. Esta clave se basa en una de las ramas específicas del perfil de hardware, en lugar de HKEY_LOCAL_MACHINE.

[in] HwProfile

Perfil de hardware para el que se va a crear una clave si HwProfileFlags está establecido en SPDICS_FLAG_CONFIGSPECIFIC. Si HwProfile es 0, se crea la clave del perfil de hardware actual. Si HwProfileFlags es SPDICS_FLAG_GLOBAL, se omite HwProfile .

[in] KeyType

Tipo de clave de almacenamiento del Registro que se va a crear. Puede ser uno de los siguientes valores:

DIREG_DEV

Cree una clave de hardware para el dispositivo.

DIREG_DRV

Cree una clave de software para el dispositivo.

[in, optional] InfHandle

Identificador de un archivo INF abierto que contiene una sección INF DDInstall que se va a ejecutar para la clave recién creada. Este parámetro es opcional y puede ser NULL. Si se especifica este parámetro, también se debe especificar InfSectionName .

[in, optional] InfSectionName

Nombre de una sección INF DDInstall del archivo INF especificado por InfHandle. Esta sección se ejecuta para la clave recién creada. Este parámetro es opcional y puede ser NULL. Si se especifica este parámetro, también se debe especificar InfHandle .

Valor devuelto

Si SetupDiCreateDevRegKey se realiza correctamente, la función devuelve un identificador a la clave del Registro especificada en la que se pueden almacenar y recuperar datos de configuración específicos del dispositivo. Si se produce un error en SetupDiCreateDevRegKey , la función devuelve INVALID_HANDLE_VALUE. Llame a GetLastError para obtener información extendida sobre el error.

Comentarios

El autor de la llamada de SetupDiCreateDevRegKey debe ser miembro del grupo Administradores.

Cierre el identificador devuelto desde SetupDiCreateDevRegKey llamando a RegCloseKey.

Si la clave especificada ya existe, SetupDiCreateDevRegKey devuelve un identificador a esa clave. De lo contrario, SetupDiCreateDevRegKey crea la clave especificada y devuelve un identificador a la nueva clave. Para Windows Server 2003 y versiones posteriores de Windows, el identificador de clave solo tiene acceso KEY_READ y KEY_WRITE. En el caso de las versiones anteriores de Windows, este identificador tiene KEY_ALL_ACCESS acceso.

La instancia de dispositivo especificada debe registrarse antes de llamar a SetupDiCreateDevRegKey . Sin embargo, tenga en cuenta que el sistema operativo registra automáticamente las instancias de dispositivo PnP. Para obtener información sobre cómo registrar instancias de dispositivo que no son PnP, consulte SetupDiRegisterDeviceInfo.

Para las instalaciones que usan archivos de diseño (especificados por la entrada LayoutFile en una sección Versión inf), el archivo de diseño debe abrirse mediante una llamada a SetupOpenAppendInfFile (que se describe en la documentación de Microsoft Windows SDK) antes de llamar a SetupDiCreateDevRegKey.

Si el conjunto de información del dispositivo proporcionado contiene elementos de información del dispositivo para un sistema remoto y también se especifican InfHandle e InfSectionName , se producirá un error en la solicitud de creación y se devolverá una llamada posterior a GetLastError ERROR_REMOTE_REQUEST_UNSUPPORTED.

Nota

El encabezado setupapi.h define SetupDiCreateDevRegKey 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