Função SetupDiOpenDeviceInterfaceW (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 SetupDiOpenDeviceInterfaceW(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PCWSTR                    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 a seguir.

[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 como sizeof(SP_DEVICE_INTERFACE_DATA) antes de chamar SetupDiOpenDeviceInterface. Para obter mais informações, consulte a seção Comentários a seguir.

Retornar valor

SetupDiOpenDeviceInterface retornará TRUE se a função for concluída sem erro. 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.

Comentários

Se um elemento de interface do dispositivo para a interface já existir em 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 posteriormente se tornou ativa. Se o elemento de informações do dispositivo para o dispositivo subjacente ainda não estiver presente em DeviceInfoSet, essa função criará um e o 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 DeviceInterfaceData , a função retornará FALSE e uma chamada subsequente para GetLastError retornará ERROR_INVALID_USER_BUFFER. No entanto, nessa situação, SetupDiOpenDeviceInterface adiciona a interface solicitada ao conjunto de informações do dispositivo.

Se a nova interface do dispositivo for aberta com êxito, mas o buffer DeviceInterfaceData fornecido pelo chamador for inválido, essa função retornará FALSE e GetLastError retornará ERROR_INVALID_USER_BUFFER. O erro de buffer do chamador não impede que a interface seja aberta.

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 tiver terminado de usar as informações recuperadas por SetupDiOpenDeviceInterface, o aplicativo deverá chamar SetupDiDeleteDeviceInterfaceData.

MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK atributo pode ser passado como o valor do argumento DevicePath da função SetupDiOpenDeviceInterface .

Observação

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

Confira também

SetupDiDeleteDeviceInterfaceData

SetupDiEnumDeviceInterfaces