Função SetupDiGetClassPropertyKeysExW (setupapi.h)
A função SetupDiGetClassPropertyKeysEx recupera uma matriz das chaves de propriedade do dispositivo que representam as propriedades do dispositivo definidas para uma classe de configuração de dispositivo ou uma classe de interface do dispositivo em um computador local ou remoto.
Sintaxe
WINSETUPAPI BOOL SetupDiGetClassPropertyKeysExW(
[in] const GUID *ClassGuid,
[out, optional] DEVPROPKEY *PropertyKeyArray,
[in] DWORD PropertyKeyCount,
[out, optional] PDWORD RequiredPropertyKeyCount,
[in] DWORD Flags,
[in, optional] PCWSTR MachineName,
PVOID Reserved
);
Parâmetros
[in] ClassGuid
Um ponteiro para um GUID que representa uma classe de configuração de dispositivo ou uma classe de interface do dispositivo. SetupDiGetClassPropertyKeysEx recupera uma matriz das chaves de propriedade do dispositivo que representam as propriedades do dispositivo definidas para a classe especificada. Para obter informações sobre como especificar o tipo de classe, consulte o parâmetro Flags .
[out, optional] PropertyKeyArray
Um ponteiro para um buffer que recebe uma matriz de valores do tipo DEVPROPKEY, em que cada valor é uma chave de propriedade do dispositivo que representa uma propriedade de dispositivo definida para a classe de configuração do dispositivo. O ponteiro é opcional e pode ser NULL. Para obter mais informações, consulte a seção Comentários mais adiante neste tópico.
[in] PropertyKeyCount
O tamanho, em valores de tipo DEVPROPKEY, do buffer PropertyKeyArray . Se PropertyKeyArray estiver definido como NULL, PropertyKeyCount deverá ser definido como zero.
[out, optional] RequiredPropertyKeyCount
Um ponteiro para uma variável do tipo DWORD que recebe o número de chaves de propriedade solicitadas. O ponteiro é opcional e pode ser definido como NULL.
[in] Flags
Um dos valores a seguir, que especifica se as chaves de propriedade de classe devem ser recuperadas para uma classe de configuração de dispositivo ou para uma classe de interface do dispositivo.
DICLASSPROP_INSTALLER
ClassGuid especifica uma classe de configuração de dispositivo. Esse sinalizador não pode ser usado com DICLASSPROP_INTERFACE.
DICLASSPROP_INTERFACE
ClassGuid especifica uma classe de interface do dispositivo. Esse sinalizador não pode ser usado com DICLASSPROP_INSTALLER.
[in, optional] MachineName
Um ponteiro para uma cadeia de caracteres terminada em NULL que contém o nome UNC, incluindo o prefixo "\" de um computador. O ponteiro pode ser NULL. Se o ponteiro for NULL, SetupDiGetClassPropertyKeysEx recuperará as informações solicitadas do 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
Esse parâmetro deve ser definido como NULL.
Retornar valor
SetupDiGetClassPropertyKeysEx retornará TRUE se for bem-sucedido. Caso contrário, ele retornará FALSE e o erro registrado poderá ser recuperado chamando GetLastError.
A tabela a seguir inclui alguns dos códigos de erro mais comuns que essa função pode registrar.
| Código de retorno | Descrição |
|---|---|
|
O valor de Flags não é válido. |
|
Se o sinalizador DICLASSPROP_INSTALLER for especificado, esse código de erro indicará que a classe de instalação do dispositivo especificada por ClassGuid não existe. |
|
A cadeia de caracteres de referência para a interface do dispositivo especificada por ClassGuild não é válida. Esse erro pode ser retornado quando o sinalizador DICLASSPROP_INTERFACE é especificado. |
|
Um valor de dados não especificado não é válido. Uma possibilidade é que o valor ClassGuid não seja válido. |
|
Um parâmetro não especificado não é válido. |
|
Um buffer de usuário não é válido. Uma possibilidade é que PropertyKeyArray seja NULL e PropertKeyCount não seja zero. |
|
O nome do computador especificado por MachineName não é válido. |
|
Se o sinalizador DICLASSPROP_INTERFACE for especificado, esse código de erro indicará que a classe de interface do dispositivo especificada por ClassGuid não existe. |
|
O buffer PropertyKeyArray não é grande o suficiente para manter todas as chaves de propriedade ou um buffer de dados interno que foi passado para uma chamada do sistema era muito pequeno. |
|
Não havia memória do sistema suficiente disponível para concluir a operação. |
|
O chamador não tem privilégios de Administrador. |
Comentários
SetupDiGetClassPropertyKeysEx faz parte do modelo de propriedade do dispositivo unificado.
Um chamador de SetupDiGetClassPropertyKeysEx deve ser um membro do grupo Administradores para recuperar chaves de propriedade do dispositivo para uma classe de dispositivo.
Se o buffer PropertyKeyArray não for grande o suficiente para manter todas as chaves de propriedade solicitadas, SetupDiGetClassPropertyKeysEx não recuperará nenhuma chave de propriedade e retornará ERROR_INSUFFICIENT_BUFFER. Se o chamador forneceu um ponteiro RequiredPropertyKeyCount, SetupDiGetClassPropertyKeysEx define o valor de *RequiredPropertyKeyCount como o tamanho necessário, em valores do tipo DEVPROPKEY, do buffer PropertyKeyArray.
Para recuperar uma propriedade de classe de dispositivo em um computador remoto, chame SetupDiGetClassPropertyEx e, para definir uma propriedade de classe de dispositivo em um computador remoto, chame SetupDiSetClassPropertyEx.
Para recuperar as chaves de propriedade de uma classe de configuração de dispositivo ou classe de interface de dispositivo em um computador local, chame SetupDiGetClassPropertyKeys.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível no Windows Vista e versões posteriores do Windows. |
| Plataforma de Destino | DesktopPara universal, chame CM_Get_Class_Property_Keys_Ex |
| Cabeçalho | setupapi.h (inclua Setupapi.h) |
| Biblioteca | Setupapi.lib |