Função SetupDiCreateDeviceInfoA (setupapi.h)

Artigo
08/26/2023

A função SetupDiCreateDeviceInfo cria um novo elemento de informações do dispositivo e o adiciona como um novo membro ao conjunto de informações do dispositivo especificado.

Sintaxe

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

Um identificador para as informações do dispositivo definidas para o computador local.

[in] DeviceName

Um ponteiro para uma cadeia de caracteres terminada em NULL que fornece uma ID de instância de dispositivo completa (por exemplo, "Root*PNP0500\0000") ou uma ID de dispositivo enumerada raiz sem o prefixo do enumerador e o sufixo do identificador de instância (por exemplo, "*PNP0500"). O identificador de dispositivo enumerado por raiz só poderá ser usado se o sinalizador DICD_GENERATE_ID for especificado no parâmetro CreationFlags .

[in] ClassGuid

Um ponteiro para o GUID da classe de configuração do dispositivo para o dispositivo. Se a classe de configuração do dispositivo não for conhecida, defina *ClassGuid como uma estrutura de GUID_NULL.

[in, optional] DeviceDescription

Um ponteiro para uma cadeia de caracteres terminada em NULL que fornece a descrição do texto do dispositivo. Esse ponteiro é opcional e pode ser NULL.

[in, optional] hwndParent

Um identificador para a janela de nível superior a ser usada para qualquer interface do usuário relacionada à instalação do dispositivo. Esse identificador é opcional e pode ser NULL.

[in] CreationFlags

Uma variável do tipo DWORD que controla como o elemento de informações do dispositivo é criado. Pode ser uma combinação dos seguintes valores:

DICD_GENERATE_ID

Se esse sinalizador for especificado, DeviceName conterá apenas uma ID de dispositivo enumerado raiz e o sistema usará essa ID para gerar uma ID de instância de dispositivo completa para o novo elemento de informações do dispositivo.

Chame SetupDiGetDeviceInstanceId para recuperar a ID da instância do dispositivo que foi gerada para esse elemento de informações do dispositivo.

DICD_INHERIT_CLASSDRVS

Se esse sinalizador for especificado, o elemento de informações do dispositivo resultante herdará a lista de drivers de classe, se houver, associada ao conjunto de informações do dispositivo. Além disso, se houver um driver selecionado para o conjunto de informações do dispositivo, esse mesmo driver será selecionado para o novo elemento de informações do dispositivo.

[out, optional] DeviceInfoData

Um ponteiro para uma estrutura SP_DEVINFO_DATA que recebe o novo elemento de informações do dispositivo. Esse ponteiro é opcional e pode ser NULL. Se a estrutura for fornecida, o chamador deverá definir o membro cbSize dessa estrutura como sizeof(SP_DEVINFO_DATA) antes de chamar a função. Para obter mais informações, consulte a seção Comentários a seguir.

Valor retornado

A função retornará TRUE se for bem-sucedida. Caso contrário, ele retornará FALSE e o erro registrado poderá ser recuperado fazendo uma chamada para GetLastError.

Comentários

O chamador dessa função deve ser membro do grupo Administradores.

Se essa instância de dispositivo estiver sendo adicionada a um conjunto que tenha uma classe associada, a classe de dispositivo deverá ser a mesma ou a chamada falhará. Nesse caso, uma chamada para GetLastError retorna ERROR_CLASS_MISMATCH.

Se a instância de dispositivo especificada for igual a uma chave de instância de dispositivo existente no registro, a chamada falhará. Nesse caso, uma chamada para GetLastError retorna ERROR_DEVINST_ALREADY_EXISTS. Isso ocorrerá somente se o sinalizador DICD_GENERATE_ID não estiver definido.

Se o novo elemento de informações do dispositivo tiver sido criado com êxito, mas o buffer DeviceInfoData fornecido pelo chamador for inválido, a função retornará FALSE. Nesse caso, uma chamada para GetLastError retorna ERROR_INVALID_USER_BUFFER. No entanto, o elemento de informações do dispositivo já terá sido adicionado como um novo membro do conjunto.

O DeviceInfoSet deve conter apenas elementos no computador local.

Observação

O cabeçalho setupapi.h define SetupDiCreateDeviceInfo 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


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