Função SetupDiRegisterDeviceInfo (setupapi.h)
A função SetupDiRegisterDeviceInfo é o manipulador padrão para a solicitação de DIF_REGISTERDEVICE .
Sintaxe
WINSETUPAPI BOOL SetupDiRegisterDeviceInfo(
[in] HDEVINFO DeviceInfoSet,
[in, out] PSP_DEVINFO_DATA DeviceInfoData,
[in] DWORD Flags,
[in, optional] PSP_DETSIG_CMPPROC CompareProc,
[in, optional] PVOID CompareContext,
[out, optional] PSP_DEVINFO_DATA DupDeviceInfoData
);
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 a ser registrado. O conjunto de informações do dispositivo não deve conter elementos remotos.
[in, out] DeviceInfoData
Um ponteiro para uma estrutura SP_DEVINFO_DATA que especifica o elemento de informações do dispositivo em DeviceInfoSet. Esse é um parâmetro IN-OUT porque DeviceInfoData.DevInst pode ser atualizado com um novo valor de identificador no retorno.
[in] Flags
Um valor de sinalizador que controla como o dispositivo é registrado, que pode ser zero ou o seguinte valor:
SPRDI_FIND_DUPS
Pesquise uma instância de dispositivo existente anteriormente que corresponda ao dispositivo representado por DeviceInfoData. Se esse sinalizador não for especificado, a instância do dispositivo será registrada independentemente de uma instância de dispositivo já existir para ela.
Se o chamador fornecer CompareProc, o chamador também deverá definir esse sinalizador.
[in, optional] CompareProc
Um ponteiro para uma função de retorno de chamada de comparação a ser usada na detecção duplicada. Esse parâmetro é opcional e pode ser NULL. Se esse parâmetro for especificado, a função de retorno de chamada será chamada para cada instância de dispositivo da mesma classe que a instância do dispositivo que está sendo registrada. O protótipo da função de retorno de chamada é o seguinte:
typedef DWORD (CALLBACK* PSP_DETSIG_CMPPROC) (
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA NewDeviceData,
IN PSP_DEVINFO_DATA ExistingDeviceData,
IN PVOID CompareContextOPTIONAL
);
A função compare deverá retornar ERROR_DUPLICATE_FOUND se descobrir que os dois dispositivos são duplicados. Caso contrário, ele deverá retornar NO_ERROR. Se algum outro erro for encontrado, a função de retorno de chamada deverá retornar o código ERROR_* apropriado para indicar a falha.
Se CompareProc não for especificado e a detecção de duplicação for solicitada, um comportamento de comparação padrão será usado. O padrão é comparar a assinatura de detecção do novo dispositivo com a assinatura de detecção de todos os outros dispositivos na classe . A assinatura de detecção está contida no descritor de recursos específico da classe da configuração de log de inicialização do dispositivo.
[in, optional] CompareContext
Um ponteiro para um buffer de contexto fornecido pelo chamador que é passado para a função de retorno de chamada. Esse parâmetro será ignorado se CompareProc não for especificado.
[out, optional] DupDeviceInfoData
Um ponteiro para uma estrutura SP_DEVINFO_DATA para receber informações sobre uma instância de dispositivo duplicada, se houver, descoberta como resultado da tentativa de registrar esse dispositivo. Esse parâmetro é opcional e pode ser NULL. Se esse parâmetro for especificado, o chamador deverá definir DupDeviceInfoData.cbSize to sizeof(SP_DEVINFO_DATA). Isso será preenchido se a função retornar FALSE e GetLastError retornar ERROR_DUPLICATE_FOUND. Esse elemento de informações do dispositivo é adicionado como um membro do DeviceInfoSet especificado, se ainda não for um membro. Se DupDeviceInfoData não for especificado, a duplicata não será adicionada ao conjunto de informações do dispositivo.
Se você chamar essa função ao lidar com uma solicitação DIF_REGISTERDEVICE , o parâmetro DupDeviceInfoData deverá ser NULL.
Retornar valor
A função retornará TRUE se for bem-sucedida. Caso contrário, ele retornará FALSE e o erro registrado poderá ser recuperado com uma chamada para GetLastError.
Comentários
SetupDiRegisterDeviceInfo foi projetado principalmente para registrar um dispositivo não PnP com o gerenciador de Plug and Play (PnP) em um computador local. Embora SetupDiRegisterDeviceInfo não falhe se o conjunto de informações do dispositivo for para um computador remoto, o resultado é de uso limitado porque o conjunto de informações do dispositivo não pode ser usado posteriormente com solicitações de instalação DIF_Xxx ou funções SetupDiXxx que não dão suporte a operações em um computador remoto. Por exemplo, chamar SetupDiCreateDevRegKey para executar uma seção INF para um dispositivo recém-registrado em um computador remoto falhará.
Não chame diretamente essa função para instâncias de dispositivo PnP. As instâncias de dispositivo PnP são registradas automaticamente pelo sistema operacional. No entanto, você deve registrar instâncias de dispositivo não PnP de uma das seguintes maneiras:
- Se o aplicativo de instalação usar uma solicitação DIF_DETECT para detectar com êxito um dispositivo, ele também deverá usar uma solicitação DIF_REGISTERDEVICE para registrar a instância do dispositivo. A solicitação deve ser tratada da maneira padrão. (Por padrão, SetupDiCallClassInstaller primeiro chama o instalador de classe e os co-instaladores de classe para fazer a detecção duplicada e registrar a instância do dispositivo. Se esses instaladores não registrarem a instância do dispositivo, SetupDiCallClassInstallerchamará SetupDiRegisterDeviceInfo para fazer a detecção duplicada e registrar a instância do dispositivo.)
- Se o aplicativo de instalação criar uma instância de dispositivo (por exemplo, chamando SetupDiCreateDeviceInfo), mas não fizer a detecção duplicada, seu aplicativo de instalação deverá usar uma solicitação DIF_REGISTERDEVICE para registrar a instância do dispositivo. A solicitação deve ser tratada da maneira padrão, conforme descrito anteriormente.
-
Se o aplicativo de instalação criar um novo dispositivo e fizer a detecção duplicada, seu aplicativo de instalação deverá usar uma solicitação DIF_REGISTERDEVICE, mas deve impedir SetupDiCallClassInstaller de chamar SetupDiRegisterDeviceInfo. Para impedir que SetupDiCallClassInstaller chame SetupDiRegisterDeviceInfo, defina o sinalizador DI_NODI_DEFAULTACTION no membro Flags da estrutura SP_DEVINSTALL_PARAMS para a instância do dispositivo.
Se SetupDiCallClassInstaller retornar TRUE para a solicitação DIF_REGISTERDEVICE, o instalador de classe ou os co-instaladores de classe registraram a instância do dispositivo. Nesse caso, o aplicativo de instalação pode continuar a instalar o dispositivo.
Se SetupDiCallClassInstaller retornar FALSE para a solicitação DIF_REGISTERDEVICE, o instalador de classe ou os co-instaladores de classe não registraram a instância do dispositivo. Nesse caso, o aplicativo de instalação deve fazer um dos seguintes procedimentos, dependendo do último erro que GetLastError retorna para a solicitação:
- Se o último erro for ERROR_DI_DO_DEFAULT, o aplicativo de instalação poderá chamar diretamente SetupDiRegisterDeviceInfo e fornecer um CompareProc para fazer a detecção duplicada. Se essa chamada for bem-sucedida e nenhuma duplicata for encontrada, a instalação do dispositivo poderá continuar. Se uma duplicata for encontrada, SetupDiRegisterDeviceInfo retornará FALSE e o aplicativo de instalação deverá encerrar a instalação do dispositivo.
- Se o último erro não for ERROR_DI_DO_DEFAULT, o aplicativo de instalação deverá encerrar a instalação do dispositivo.
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 |
| DLL | Setupapi.dll |