Función SetupDiCreateDevRegKeyA (setupapi.h)

Artículo
11/20/2024

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, se 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

El 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 se puede NULL. Si se especifica este parámetro, también se debe especificar InfSectionName.

[in, optional] InfSectionName

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

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 de error extendida.

Observaciones

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 KEY_READ y KEY_WRITE acceso. En las versiones anteriores de Windows, este identificador tiene acceso KEY_ALL_ACCESS.

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

En el caso de las instalaciones que usan archivos de diseño (especificados por la entrada LayoutFile de en una sección versión INF), el archivo de diseño debe abrirse mediante una llamada a SetupOpenAppendAppendInfFile (que se describe en la documentación de Microsoft Windows SDK) antes de se llame a SetupDiCreateDevReg Key.

Si el conjunto de información del dispositivo proporcionado contiene elementos de información del dispositivo para un sistema remoto y infHandle y infSectionName también se especifican, se producirá un error en la solicitud de creación y se devolverá una llamada posterior a GetLastError devolverá 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 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