Função SetupDiGetClassDevsW (setupapi.h)

Artigo
08/26/2023

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

Sintaxe

WINSETUPAPI HDEVINFO SetupDiGetClassDevsW(
  [in, optional] const GUID *ClassGuid,
  [in, optional] PCWSTR     Enumerator,
  [in, optional] HWND       hwndParent,
  [in]           DWORD      Flags
);

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. Para obter mais informações sobre como definir 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) ou o nome simbólico do valor. Por exemplo, "PCI" pode ser usado para especificar o valor PnP PCI. Outros exemplos de nomes simbólicos para valores PnP incluem "USB", "PCMCIA" e "SCSI".
Uma ID da instância do dispositivo PnP. Ao especificar uma ID de instância de dispositivo PnP, DIGCF_DEVICEINTERFACE deve ser definido no parâmetro Flags.

Esse ponteiro é opcional e pode ser NULL. Se um valor de enumeração 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 usada 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 zero ou mais dos sinalizadores a seguir. Para obter mais informações sobre como combinar esses sinalizadores, consulte a seção Comentários a seguir.

DIGCF_ALLCLASSES

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

DIGCF_DEVICEINTERFACE

Retornar dispositivos que dão suporte a interfaces de dispositivo para as classes de interface de 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

Retornar somente o dispositivo associado à interface do dispositivo padrão do sistema, se houver um definido, para as classes de interface de dispositivo especificadas.

DIGCF_PRESENT

Retornar somente dispositivos que estão atualmente presentes em um sistema.

DIGCF_PROFILE

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

Retornar valor

Se a operação for bem-sucedida, SetupDiGetClassDevs retornará um identificador para um conjunto de informações do dispositivo que contém todos os dispositivos instalados que correspondem 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 SetupDiGetClassDevs deve excluir as informações retornadas do dispositivo definidas quando elas não forem mais necessárias chamando SetupDiDestroyDeviceInfoList.

Chame SetupDiGetClassDevsEx para recuperar os dispositivos de uma classe em um computador remoto.

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

Use as seguintes opções de filtragem para controlar se SetupDiGetClassDevs retorna dispositivos para todas as classes de configuração de 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 em combinação entre si 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 Enumerator para fornecer o GUID ou o nome simbólico do enumerador. Se Enumerador for NULL, SetupDiGetClassDevs retornará dispositivos para todos os enumeradores PnP.

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

Use as seguintes opções de filtragem para controlar se SetupDiGetClassDevs 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 somente 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 definir um elemento de informações do dispositivo que representa esse dispositivo e, em seguida, 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 SetupDiGetClassDevs 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 definir um elemento de informações do dispositivo que representa esse dispositivo e, em seguida, 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 definir um elemento de informações do dispositivo que representa esse dispositivo e, em seguida, 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 seguintes opções 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 DIGCF_DEVICEINTERFACE e use o parâmetro Enumerador para fornecer a ID da instância do dispositivo. Para incluir todos os dispositivos possíveis, defina Enumerador como NULL.

Exemplos

Veja a seguir alguns exemplos de como usar a função SetupDiGetClassDevs .

Exemplo 1: Crie uma lista de todos os dispositivos no sistema, incluindo dispositivos que não estão presentes no momento.

Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES);

Exemplo 2: Crie uma lista de todos os dispositivos presentes no sistema.

Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES | DIGCF_PRESENT);

Exemplo 3: Crie uma lista de todos os dispositivos presentes no sistema que são da classe de configuração do dispositivo do adaptador de rede.

Handle = SetupDiGetClassDevs(&GUID_DEVCLASS_NET, NULL, NULL, DIGCF_PRESENT);

Exemplo 4: Crie uma lista de todos os dispositivos presentes no sistema que habilitaram uma interface da classe de interface do dispositivo de volume de armazenamento.

Handle = SetupDiGetClassDevs(&GUID_DEVINTERFACE_VOLUME, NULL, NULL, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);

Exemplo 5: Crie uma lista de todos os dispositivos que estão presentes no sistema, mas não pertencem a nenhuma classe de configuração de dispositivo conhecida (Windows Vista e versões posteriores do Windows).

Nota Não é possível definir o parâmetro ClassGuid como GUID_DEVCLASS_UNKNOWN para detectar dispositivos com uma classe de configuração desconhecida. Em vez disso, você deve seguir este exemplo.

DeviceInfoSet = SetupDiGetClassDevs(
                                    NULL,
                                    NULL,
                                    NULL,
                                    DIGCF_ALLCLASSES | DIGCF_PRESENT);

ZeroMemory(&DeviceInfoData, sizeof(SP_DEVINFO_DATA));
DeviceInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
DeviceIndex = 0;
    
while (SetupDiEnumDeviceInfo(
                             DeviceInfoSet,
                             DeviceIndex,
                             &DeviceInfoData)) {
    DeviceIndex++;

    if (!SetupDiGetDeviceProperty(
                                  DeviceInfoSet,
                                  &DeviceInfoData,
                                  &DEVPKEY_Device_Class,
                                  &PropType,
                                  (PBYTE)&DevGuid,
                                  sizeof(GUID),
                                  &Size,
                                  0) || PropType != DEVPROP_TYPE_GUID) {

        Error = GetLastError();

        if (Error == ERROR_NOT_FOUND) {
            \\
            \\ This device has an unknown device setup class.
            \\
            }
        }                 
    }

if (DeviceInfoSet) {
    SetupDiDestroyDeviceInfoList(DeviceInfoSet);
    }

Observação

O cabeçalho setupapi.h define SetupDiGetClassDevs 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	DesktopPara universal, chame CM_Get_Device_ID_ListFor universal, chame CM_Get_Device_Interface_List
Cabeçalho	setupapi.h (inclua SetupAPI.h)
Biblioteca	SetupAPI.lib
DLL	SetupAPI.dll
Conjunto de APIs	ext-ms-win-setupapi-classinstallers-l1-1-0 (introduzido no Windows 8)