Função SetupDiCreateDevRegKeyA (setupapi.h)

A função SetupDiCreateDevRegKey cria uma chave do Registro para informações de configuração específicas do dispositivo e retorna um identificador para a chave.

Sintaxe

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

Um identificador para um conjunto de informações do dispositivo que contém um elemento de informações do dispositivo que representa o dispositivo para o qual criar uma chave do Registro.

[in] DeviceInfoData

Um ponteiro para uma estrutura SP_DEVINFO_DATA que especifica o elemento de informações do dispositivo em DeviceInfoSet.

[in] Scope

O escopo da chave do Registro a ser criada. O escopo determina onde as informações são armazenadas. A chave criada pode ser global ou específica do perfil de hardware. Pode ser um dos seguintes valores:

DICS_FLAG_GLOBAL

Crie uma chave para armazenar informações de configuração global. Essas informações não são específicas para um perfil de hardware específico. Em sistemas operacionais baseados em NT, isso cria uma chave com raiz em HKEY_LOCAL_MACHINE. A chave exata aberta depende do valor do parâmetro KeyType .

DICS_FLAG_CONFIGSPECIFIC

Crie uma chave para armazenar informações de configuração específicas do perfil de hardware. Essa chave está enraizada em um dos branches específicos do perfil de hardware, em vez de HKEY_LOCAL_MACHINE.

[in] HwProfile

O perfil de hardware para o qual criar uma chave se HwProfileFlags estiver definido como SPDICS_FLAG_CONFIGSPECIFIC. Se HwProfile for 0, a chave para o perfil de hardware atual será criada. Se HwProfileFlags for SPDICS_FLAG_GLOBAL, HwProfile será ignorado.

[in] KeyType

O tipo de chave de armazenamento do Registro a ser criada. Pode ser um dos seguintes valores:

DIREG_DEV

Crie uma chave de hardware para o dispositivo.

DIREG_DRV

Crie uma chave de software para o dispositivo.

[in, optional] InfHandle

O identificador para um arquivo INF aberto que contém uma seção INF DDInstall a ser executada para a chave recém-criada. Esse parâmetro é opcional e pode ser NULL. Se esse parâmetro for especificado, InfSectionName também deverá ser especificado.

[in, optional] InfSectionName

O nome de uma seção INF DDInstall no arquivo INF especificado por InfHandle. Esta seção é executada para a chave recém-criada. Esse parâmetro é opcional e pode ser NULL. Se esse parâmetro for especificado, InfHandle também deverá ser especificado.

Retornar valor

Se SetupDiCreateDevRegKey for bem-sucedido, a função retornará um identificador para a chave do Registro especificada na qual os dados de configuração específicos do dispositivo podem ser armazenados e recuperados. Se SetupDiCreateDevRegKey falhar, a função retornará INVALID_HANDLE_VALUE. Chame GetLastError para obter informações de erro estendidas.

Comentários

O chamador de SetupDiCreateDevRegKey deve ser membro do grupo Administradores.

Feche o identificador retornado de SetupDiCreateDevRegKey chamando RegCloseKey.

Se a chave especificada já existir, SetupDiCreateDevRegKey retornará um identificador para essa chave. Caso contrário, SetupDiCreateDevRegKey cria a chave especificada e retorna um identificador para a nova chave. Para o Windows Server 2003 e versões posteriores do Windows, o identificador de chave tem KEY_READ e KEY_WRITE acesso apenas. Para versões anteriores do Windows, esse identificador tem acesso KEY_ALL_ACCESS.

A instância de dispositivo especificada deve ser registrada antes que SetupDiCreateDevRegKey seja chamado. Observe, no entanto, que o sistema operacional registra automaticamente instâncias de dispositivo PnP. Para obter informações sobre como registrar instâncias de dispositivo não PnP, consulte SetupDiRegisterDeviceInfo.

Para instalações que usam arquivos de layout (especificados pela entrada LayoutFile em uma seção versão inf), o arquivo de layout deve ser aberto por uma chamada para SetupOpenAppendInfFile (descrito na documentação do SDK do Microsoft Windows) antes de SetupDiCreateDevRegKey ser chamado.

Se o conjunto de informações do dispositivo fornecido contiver elementos de informações do dispositivo para um sistema remoto e InfHandle e InfSectionName também forem especificados, a solicitação de criação falhará e uma chamada subsequente para GetLastError retornará ERROR_REMOTE_REQUEST_UNSUPPORTED.

Observação

O cabeçalho setupapi.h define SetupDiCreateDevRegKey como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Disponível no Microsoft Windows 2000 e versões posteriores do Windows.
Plataforma de Destino Área de Trabalho
Cabeçalho setupapi.h (inclua Setupapi.h)
Biblioteca Setupapi.lib

Confira também

SetupDiCreateDeviceInfo

SetupDiGetHwProfileList

SetupDiOpenDevRegKey

SetupDiRegisterDeviceInfo