Compartilhar via

Função SetupDiGetClassDevsExW (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 SetupDiGetClassDevsExW(
  [in, optional] const GUID *ClassGuid,
  [in, optional] PCWSTR     Enumerator,
  [in, optional] HWND       hwndParent,
  [in]           DWORD      Flags,
  [in, optional] HDEVINFO   DeviceInfoSet,
  [in, optional] PCWSTR     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 para 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 plug and play (PnP) enumerador. 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 de PCI. Outros exemplos de nomes simbólicos para enumeradores PnP incluem "USB", "PCMCIA" e "SCSI".
  • Umade IDs de instância de dispositivo de PnP. Ao especificar uma ID da instância do dispositivo PnP, DIGCF_DEVICEINTERFACE deve ser definido no parâmetro Flags.
Esse ponteiro é opcional e pode ser NULL. Se um enumerador valor não for usado para selecionar dispositivos, defina de Enumerador para 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 seguinte seção Comentários.

DIGCF_ALLCLASSES

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

DIGCF_DEVICEINTERFACE

Retorne dispositivos que dão suporte a interfaces de dispositivo para as classes de interface do dispositivo especificadas. Esse sinalizador deve ser definido no parâmetro sinalizadores se o parâmetro Enumerador especificar uma ID da 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 os 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 de 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 de NULL para MachineName especifica que o dispositivo está instalado no computador local. Não há suporte para computador remoto começando com o Windows 8 e o Windows Server 2012.

Cuidado

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

Reserved

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

Valor de retorno

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.

Observações

O chamador do SetupDiGetClassDevsEx deve excluir o conjunto de informações do dispositivo retornado quando ele 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 instalaçã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 instalação de dispositivo, a classe de instalaçã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 instalação do dispositivo ou apenas para uma classe de instalação de dispositivo especificada:
  • Para retornar dispositivos para todas as classes de instalação do dispositivo, defina o sinalizador DIGCF_ALLCLASSES e defina o parâmetro ClassGuid para NULL.
  • Para retornar dispositivos somente para uma classe de instalação de dispositivo específica, não defina DIGCF_ALLCLASSES e use ClassGuid para fornecer o GUID da classe de instalaçã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 os 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 estiver 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 do 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 um elemento de informações do dispositivo que representa esse dispositivo e 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 de dispositivo da classe especificada à lista de interface 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 interface 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 interface 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 os dispositivos que fazem parte do perfil de hardware atual, defina o sinalizador DIGCF_PROFILE.
  • Para retornar apenas um dispositivo específico, defina o sinalizador de DIGCF_DEVICEINTERFACE e use o parâmetro Enumerador para fornecer o ID da instância do dispositivo do dispositivo. Para incluir todos os dispositivos possíveis, defina de Enumerador para NULL.

recuperação de 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 instalaçã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 no 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 de sinalizadores de como DIGCF_DEVICEINTERFACE.
    • Defina DeviceInfoSet com o identificador HDEVINFO obtido na etapa (1).
    • Defina hwndParent conforme apropriado e os parâmetros restantes para NULL.
Em uma operação desse tipo, SetupDiGetClassDevsEx retornará um dispositivo se a classe de instalaçã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.

Nota

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

Consulte também

conjunto de informações do dispositivo

IDs da instância do dispositivo

SetupDiCreateDeviceInfoListEx

SetupDiDestroyDeviceInfoList

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs