Função SetupDiOpenDeviceInfoA (setupapi.h)

Artigo
08/26/2023

A função SetupDiOpenDeviceInfo adiciona um elemento de informações de dispositivo para uma instância de dispositivo a um conjunto de informações do dispositivo, se ainda não existir no conjunto de informações do dispositivo, e recupera informações que identificam o elemento de informações do dispositivo para a instância do dispositivo no conjunto de informações do dispositivo.

Sintaxe

WINSETUPAPI BOOL SetupDiOpenDeviceInfoA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PCSTR            DeviceInstanceId,
  [in, optional]  HWND             hwndParent,
  [in]            DWORD            OpenFlags,
  [out, optional] PSP_DEVINFO_DATA DeviceInfoData
);

Parâmetros

[in] DeviceInfoSet

Um identificador para o conjunto de informações do dispositivo ao qual SetupDiOpenDeviceInfo adiciona um elemento de informações do dispositivo, se ainda não existir, para a instância do dispositivo especificada por DeviceInstanceId.

[in] DeviceInstanceId

Um ponteiro para uma cadeia de caracteres terminada em NULL que fornece o identificador de instância do dispositivo de um dispositivo (por exemplo, "Root*PNP0500\0000"). Se DeviceInstanceId for NULL ou fizer referência a uma cadeia de caracteres de comprimento zero, SetupDiOpenDeviceInfo adicionará um elemento de informações do dispositivo ao conjunto de informações do dispositivo fornecido, se ainda não existir, para o dispositivo raiz na árvore de dispositivos.

[in, optional] hwndParent

O identificador para a janela de nível superior a ser usada para qualquer interface do usuário relacionada à instalação do dispositivo.

[in] OpenFlags

Uma variável do tipo DWORD que controla como o elemento de informações do dispositivo é aberto. O valor desse parâmetro pode ser um ou mais dos seguintes:

DIOD_CANCEL_REMOVE

Se esse sinalizador for especificado e o dispositivo tiver sido marcado para remoção pendente, o sistema operacional cancelará a remoção pendente.

DIOD_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.

Se o elemento de informações do dispositivo já estiver presente, sua lista de drivers de classe, se houver, será substituída pela lista herdada.

[out, optional] DeviceInfoData

Um ponteiro para uma estrutura de SP_DEVINFO_DATA fornecida pelo chamador que recebe informações sobre o elemento de informações do dispositivo para a instância do dispositivo especificada por DeviceInstanceId. O chamador deve definir cbSize como sizeof(SP_DEVINFO_DATA). Esse parâmetro é opcional e pode ser NULL.

Retornar valor

SetupDiOpenDeviceInfo retornará TRUE se for bem-sucedido. Caso contrário, a função retornará FALSE e o erro registrado poderá ser recuperado com uma chamada para GetLastError.

Comentários

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 o novo elemento de informações do dispositivo for aberto com êxito, mas o buffer DeviceInfoData fornecido pelo chamador for inválido, essa função retornará FALSE. Nesse caso, uma chamada para GetLastError retorna ERROR_INVALID_USER_BUFFER. No entanto, o elemento de informações do dispositivo é adicionado como um novo membro do conjunto de qualquer maneira.

Observação

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