Função SetupDiGetClassDevsExA (setupapi.h)

  • Artigo

A função SetupDiGetClassDevsEx retorna um identificador para um conjunto de informações do dispositivo que contém elementos de informações de dispositivo solicitados para um computador local ou remoto.

Sintaxe

WINSETUPAPI HDEVINFO SetupDiGetClassDevsExA(
  [in, optional] const GUID *ClassGuid,
  [in, optional] PCSTR      Enumerator,
  [in, optional] HWND       hwndParent,
  [in]           DWORD      Flags,
  [in, optional] HDEVINFO   DeviceInfoSet,
  [in, optional] PCSTR      MachineName,
                 PVOID      Reserved
);

Parâmetros

[in, optional] ClassGuid

Um ponteiro para o GUID para uma classe de configuração de dispositivo ou uma classe de interface do dispositivo. Esse ponteiro é opcional e pode ser NULL. Se um valor GUID não for usado para selecionar dispositivos, defina ClassGuid como NULL. Para obter mais informações sobre como usar ClassGuid, consulte a seção Comentários a seguir.

[in, optional] Enumerator

Um ponteiro para uma cadeia de caracteres terminada em NULL que especifica:

  • Um identificador (ID) de um enumerador de Plug and Play (PnP). Essa ID pode ser o GUID (identificador global exclusivo) do enumerador ou o nome simbólico. Por exemplo, "PCI" pode ser usado para especificar o enumerador PnP PCI. Outros exemplos de nomes simbólicos para enumeradores PnP incluem "USB", "PCMCIA" e "SCSI".
  • IDs de instância de dispositivo PnP. Ao especificar uma ID de instância do dispositivo PnP, DIGCF_DEVICEINTERFACE deve ser definido no parâmetro Flags.
Esse ponteiro é opcional e pode ser NULL. Se um valor Enumerador não for usado para selecionar dispositivos, defina Enumerador como NULL

Para obter mais informações sobre como definir o valor do Enumerador , consulte a seção Comentários a seguir.

[in, optional] hwndParent

Um identificador para a janela de nível superior a ser usado para uma interface do usuário associada à instalação de uma instância de dispositivo no conjunto de informações do dispositivo. Esse identificador é opcional e pode ser NULL.

[in] Flags

Uma variável do tipo DWORD que especifica opções de controle que filtram os elementos de informações do dispositivo que são adicionados ao conjunto de informações do dispositivo. Esse parâmetro pode ser um OR bit a bit de um ou mais dos sinalizadores a seguir. Para obter mais informações sobre como combinar essas opções de controle, consulte a seção Comentários a seguir.

DIGCF_ALLCLASSES

Retornar uma lista de dispositivos instalados para as classes de configuração de dispositivo especificadas ou classes de interface do dispositivo.

DIGCF_DEVICEINTERFACE

Retornar dispositivos que dão suporte a interfaces de dispositivo para as classes de interface do dispositivo especificadas. Esse sinalizador deverá ser definido no parâmetro Flags se o parâmetro Enumerator especificar uma ID de instância do dispositivo.

DIGCF_DEFAULT

Retorne apenas o dispositivo associado à interface do dispositivo padrão do sistema, se um estiver definido, para as classes de interface do dispositivo especificadas.

DIGCF_PRESENT

Retornar somente dispositivos que estão presentes no momento.

DIGCF_PROFILE

Retornar somente dispositivos que fazem parte do perfil de hardware atual.

[in, optional] DeviceInfoSet

O identificador para um conjunto de informações de dispositivo existente ao qual SetupDiGetClassDevsEx adiciona os elementos de informações do dispositivo solicitados. Esse parâmetro é opcional e pode ser definido como NULL. Para obter mais informações sobre como usar esse parâmetro, consulte a seção Comentários a seguir.

[in, optional] MachineName

Um ponteiro para uma cadeia de caracteres constante que contém o nome de um computador remoto no qual os dispositivos residem. Um valor NULL para MachineName especifica que o dispositivo está instalado no computador local.

Cuidado

Não há suporte para o uso dessa função para acessar computadores remotos, começando com Windows 8 e Windows Server 2012, pois essa funcionalidade foi removida.

Reserved

Reservado para uso interno. Esse parâmetro deve ser definido como NULL.

Retornar valor

Se a operação for bem-sucedida, SetupDiGetClassDevsEx retornará um identificador para um conjunto de informações do dispositivo que contém todos os dispositivos instalados que corresponderam aos parâmetros fornecidos. Se a operação falhar, a função retornará INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.

Comentários

O chamador de SetupDiGetClassDevsEx deve excluir o conjunto de informações do dispositivo retornado quando não for mais necessário chamando SetupDiDestroyDeviceInfoList.

Se DeviceInfoSet for NULL, SetupDiGetClassDevsEx criará um novo conjunto de informações do dispositivo que contém os elementos de informações do dispositivo recuperados e retornará um identificador para o novo conjunto de informações do dispositivo. Se o chamador solicitar que a função recupere dispositivos para uma classe de configuração de dispositivo fornecida pelo parâmetro ClassGuid , a função definirá a classe de configuração do dispositivo das novas informações do dispositivo definidas como o GUID da classe fornecida.

Se DeviceInfoSet não estiver definido como NULL, a função adicionará os elementos de informações do dispositivo recuperados ao conjunto de informações do dispositivo associado ao identificador fornecido e retornará o identificador fornecido. Se ClassGuid fornecer uma classe de configuração de dispositivo, a classe de configuração do dispositivo do conjunto de informações do dispositivo fornecido deverá ser definida como o GUID de classe fornecido.

Opções de controle de classe de instalação do dispositivo

Use as seguintes opções de filtragem para controlar se SetupDiGetClassDevsEx retorna dispositivos para todas as classes de configuração do dispositivo ou apenas para uma classe de configuração de dispositivo especificada:
  • Para retornar dispositivos para todas as classes de configuração de dispositivo, defina o sinalizador DIGCF_ALLCLASSES e defina o parâmetro ClassGuid como NULL.
  • Para retornar dispositivos somente para uma classe de configuração de dispositivo específica, não defina DIGCF_ALLCLASSES e use ClassGuid para fornecer o GUID da classe de configuração do dispositivo.
Além disso, você pode usar as seguintes opções de filtragem para restringir ainda mais quais dispositivos são retornados.
  • Para retornar apenas os dispositivos presentes no sistema, defina o sinalizador DIGCF_PRESENT.
  • Para retornar apenas dispositivos que fazem parte do perfil de hardware atual, defina o sinalizador DIGCF_PROFILE.
  • Para retornar dispositivos somente para um enumerador PnP específico, use o parâmetro Enumerador para fornecer o GUID ou o nome simbólico do enumerador. Se Enumerador for NULL, SetupDiGetClassDevsEx retornará dispositivos para todos os enumeradores PnP.

Opções de controle de classe de interface do dispositivo

Use as seguintes opções de filtragem para controlar se SetupDiGetClassDevsEx retorna dispositivos que dão suporte a qualquer classe de interface do dispositivo ou apenas dispositivos que dão suporte a uma classe de interface de dispositivo especificada:
  • Para retornar dispositivos que dão suporte a uma interface de dispositivo de qualquer classe, defina o sinalizador DIGCF_DEVICEINTERFACE, defina o sinalizador DIGCF_ALLCLASSES e defina ClassGuid como NULL. A função adiciona às informações do dispositivo definir um elemento de informações do dispositivo que representa esse dispositivo e, em seguida, adiciona ao elemento de informações do dispositivo uma lista de interface do dispositivo que contém todas as interfaces de dispositivo compatíveis com o dispositivo.
  • Para retornar apenas dispositivos que dão suporte a uma interface de dispositivo de uma classe especificada, defina o sinalizador DIGCF_DEVICEINTERFACE e use o parâmetro ClassGuid para fornecer o GUID de classe da classe de interface do dispositivo. A função adiciona às informações do dispositivo um elemento de informações do dispositivo que representa esse dispositivo e adiciona uma interface do dispositivo da classe especificada à lista de interfaces do dispositivo para esse elemento de informações do dispositivo.
Além disso, você pode usar as seguintes opções de filtragem para controlar se SetupDiGetClassDevsEx retorna apenas dispositivos que dão suporte à interface padrão do sistema para classes de interface do dispositivo:
  • Para retornar apenas o dispositivo que dá suporte à interface padrão do sistema, se um estiver definido, para uma classe de interface de dispositivo especificada, defina o sinalizador DIGCF_DEVICEINTERFACE, defina o sinalizador DIGCF_DEFAULT e use ClassGuid para fornecer o GUID de classe da classe de interface do dispositivo. A função adiciona às informações do dispositivo um elemento de informações do dispositivo que representa esse dispositivo e adiciona a interface padrão do sistema à lista de interfaces do dispositivo para esse elemento de informações do dispositivo.
  • Para retornar um dispositivo que dê suporte a uma interface padrão do sistema para uma classe de interface de dispositivo não especificada, defina o sinalizador DIGCF_DEVICEINTERFACE, defina o sinalizador DIGCF_ALLCLASSES, defina o sinalizador DIGCF_DEFAULT e defina ClassGuid como NULL. A função adiciona às informações do dispositivo um elemento de informações do dispositivo que representa esse dispositivo e adiciona a interface padrão do sistema à lista de interfaces do dispositivo para esse elemento de informações do dispositivo.
Você também pode usar as opções a seguir em combinação com as outras opções para restringir ainda mais quais dispositivos são retornados.
  • Para retornar apenas os dispositivos presentes no sistema, defina o sinalizador DIGCF_PRESENT.
  • Para retornar apenas dispositivos que fazem parte do perfil de hardware atual, defina o sinalizador DIGCF_PROFILE.
  • Para retornar apenas um dispositivo específico, defina o sinalizador DIGCF_DEVICEINTERFACE e use o parâmetro Enumerator para fornecer a ID da instância do dispositivo. Para incluir todos os dispositivos possíveis, defina Enumerador como NULL.

Recuperando dispositivos em uma classe de instalação de dispositivo que dá suporte a uma classe de interface do dispositivo

Um instalador pode usar SetupDiGetClassDevsEx para recuperar uma lista de dispositivos de uma classe de configuração de dispositivo específica que dão suporte a uma interface de dispositivo de uma classe de interface de dispositivo especificada. Por exemplo, para recuperar uma lista de todos os dispositivos em um computador local que dão suporte a uma interface de dispositivo na classe de interface "dispositivo montado" e que são membros da classe de instalação do dispositivo "Volume", um instalador deve executar as seguintes operações:
  1. Chame SetupDiCreateDeviceInfoList para criar um conjunto de informações de dispositivo vazio para a classe de configuração do dispositivo "Volume". Defina ClassGuid como um ponteiro para o GUID de classe para a classe de configuração do dispositivo "Volume" e defina hwndParent conforme apropriado. Em resposta a essa chamada, a função retornará um identificador para digitar HDEVINFO para o conjunto de informações do dispositivo.
  2. Chame SetupDiGetClassDevsEx com as seguintes configurações:
    • Defina ClassGuid como um ponteiro para o GUID de classe da classe de interface do dispositivo "dispositivo montado".
    • Defina Sinalizadores como DIGCF_DEVICEINTERFACE.
    • Defina DeviceInfoSet como o identificador HDEVINFO obtido na etapa (1).
    • Defina hwndParent conforme apropriado e os parâmetros restantes como NULL.
Em uma operação desse tipo, SetupDiGetClassDevsEx retornará um dispositivo se a classe de configuração do dispositivo for igual ao conjunto de informações do dispositivo fornecido e se o dispositivo oferecer suporte a uma interface do dispositivo cuja classe é a mesma da classe de interface do dispositivo especificada.

Observação

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

Conjunto de Informações do Dispositivo

IDs de instância do dispositivo

SetupDiCreateDeviceInfoListEx

SetupDiDestroyDeviceInfoList

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs