Função SetupDiOpenDeviceInterfaceA (setupapi.h)
A função SetupDiOpenDeviceInterface recupera informações sobre uma interface do dispositivo e adiciona a interface ao conjunto de informações do dispositivo especificado para um sistema local ou um sistema remoto.
Sintaxe
WINSETUPAPI BOOL SetupDiOpenDeviceInterfaceA(
[in] HDEVINFO DeviceInfoSet,
[in] PCSTR DevicePath,
[in] DWORD OpenFlags,
[out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);
Parâmetros
[in] DeviceInfoSet
Um ponteiro para um conjunto de informações do dispositivo que contém ou conterá um elemento de informações do dispositivo que representa o dispositivo que dá suporte à interface a ser aberta.
[in] DevicePath
Um ponteiro para uma cadeia de caracteres terminada em NULL que fornece o nome da interface do dispositivo a ser aberta. Esse nome é um caminho de dispositivo Win32 que normalmente é recebido em uma estrutura de notificação PnP ou obtido por uma chamada anterior para SetupDiEnumDeviceInterfaces e suas funções relacionadas.
[in] OpenFlags
Sinalizadores que determinam como o elemento de interface do dispositivo deve ser aberto. O único sinalizador válido é o seguinte:
DIODI_NO_ADD
Especifica que o elemento de informações do dispositivo para o dispositivo subjacente não será criado se esse elemento ainda não estiver presente no conjunto de informações do dispositivo especificado. Para obter mais informações, consulte a seção comentários
[out, optional] DeviceInterfaceData
Um ponteiro para uma estrutura de SP_DEVICE_INTERFACE_DATA inicializada pelo chamador que recebe os dados de interface solicitados. Esse ponteiro é opcional e pode ser NULL. Se um buffer for fornecido, o chamador deverá definir o membro cbSize da estrutura para sizeof(SP_DEVICE_INTERFACE_DATA) antes de chamar SetupDiOpenDeviceInterface. Para obter mais informações, consulte a seção comentários
Valor de retorno
SetupDiOpenDeviceInterface retornará verdadeiro se a função for concluída sem erros. Se a função for concluída com um erro, ela retornará FALSE e o código de erro da falha poderá ser recuperado chamando GetLastError.
Observações
Se já existir um elemento de interface do dispositivo para a interface no DeviceInfoSet, SetupDiOpenDeviceInterface atualizará os sinalizadores. Portanto, essa função pode ser usada para atualizar os sinalizadores de uma interface do dispositivo. Por exemplo, uma interface pode ter sido inativa quando foi aberta pela primeira vez, mas se tornou ativa posteriormente. Se o elemento de informações do dispositivo subjacente ainda não estiver presente em DeviceInfoSet, essa função criará uma e a adicionará a DeviceInfoSet.
Se a função abrir com êxito a nova interface do dispositivo, mas o chamador não fornecer uma estrutura válida no parâmetro
Se a nova interface do dispositivo for aberta com êxito, mas o buffer de DeviceInterfaceData
Se o sinalizador DIODI_NO_ADD for especificado para o parâmetro OpenFlags e um elemento de informações do dispositivo subjacente ainda não estiver presente no conjunto de informações do dispositivo especificado, essa função retornará false e GetLastError retornará ERROR_NO_SUCH_DEVICE_INTERFACE.
Quando o aplicativo terminar de usar as informações que SetupDiOpenDeviceInterface recuperado, o aplicativo deve chamar SetupDiDeleteDeviceInterfaceData.
Nota
O cabeçalho setupapi.h define SetupDiOpenDeviceInterface 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 |