Função SetupDiCreateDeviceInfoA (setupapi.h)

Artigo
11/20/2024

A função SetupDiCreateDeviceInfo cria um novo elemento de informações do dispositivo e adiciona-o 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 o conjunto de informações do dispositivo 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 enumerador e o sufixo do identificador de instância (por exemplo, "*PNP0500"). O identificador de dispositivo enumerado raiz só poderá ser usado se o sinalizador DICD_GENERATE_ID for especificado no parâmetro CreationFlags.

[in] ClassGuid

Um ponteiro para a classe de instalação do dispositivo GUID para o dispositivo. Se a classe de configuração do dispositivo não for conhecida, defina * ClassGuid para uma estrutura 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 usado 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 enumerada 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 driver 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 para sizeof(SP_DEVINFO_DATA) antes de chamar a função. Para obter mais informações, consulte a seção comentários a seguir.

Valor de retorno

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.

Observações

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

Se essa instância do 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 do dispositivo especificada for a mesma que 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 de DICD_GENERATE_ID não estiver definido.

Se o novo elemento de informações do dispositivo foi criado com êxito, mas o buffer de 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.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível no Microsoft Windows 2000 e versões posteriores do Windows.
da Plataforma de Destino	Área de trabalho
cabeçalho	setupapi.h (inclua Setupapi.h)
biblioteca	Setupapi.lib

Consulte também

SP_DEVINFO_DATA

setupDiDeleteDeviceInfo

SetupDiEnumDeviceInfo

SetupDiOpenDeviceInfo

Compartilhar via