Função SetupDiCreateDeviceInfoA (setupapi.h)
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 |