Função SetupDiGetClassPropertyExW (setupapi.h)
A função SetupDiGetClassPropertyEx recupera uma propriedade de classe para uma classe de configuração de dispositivo ou uma classe de interface de dispositivo em um computador local ou remoto.
Sintaxe
WINSETUPAPI BOOL SetupDiGetClassPropertyExW(
[in] const GUID *ClassGuid,
[in] const DEVPROPKEY *PropertyKey,
[out] DEVPROPTYPE *PropertyType,
[out, optional] PBYTE PropertyBuffer,
[in] DWORD PropertyBufferSize,
[out, optional] PDWORD RequiredSize,
[in] DWORD Flags,
[in, optional] PCWSTR MachineName,
PVOID Reserved
);
Parâmetros
[in] ClassGuid
Um ponteiro para um GUID que identifica a classe de configuração do dispositivo ou a classe de interface do dispositivo para a qual recuperar uma propriedade de dispositivo para a classe de dispositivo. Para obter informações sobre como especificar o tipo de classe, consulte o parâmetro Flags .
[in] PropertyKey
Um ponteiro para uma estrutura DEVPROPKEY que representa a chave de propriedade do dispositivo da propriedade de classe de dispositivo solicitada.
[out] PropertyType
Um ponteiro para uma variável do tipo DEVPROPTYPE que recebe o identificador property-data-type da propriedade de classe de dispositivo solicitada, em que o identificador de tipo de dados de propriedade é o OR bit a bit entre um identificador de tipo de dados base e, se o tipo de dados base for modificado, um modificador de tipo de dados de propriedade.
[out, optional] PropertyBuffer
Um ponteiro para um buffer que recebe a propriedade de classe de dispositivo solicitada. SetupDiGetClassPropertyEx recupera o valor da propriedade solicitada somente se o buffer for grande o suficiente para manter todos os dados de valor da propriedade. O ponteiro pode ser NULL. Se o ponteiro estiver definido como NULL e RequiredSize for fornecido, SetupDiGetClassPropertyEx retornará o tamanho da propriedade de classe de dispositivo, em bytes, em *RequiredSize.
[in] PropertyBufferSize
O tamanho, em bytes, do buffer PropertyBuffer . Se PropertyBuffer estiver definido como NULL, PropertyBufferSize deverá ser definido como zero.
[out, optional] RequiredSize
Um ponteiro para uma variável do tipo DWORD que recebe o tamanho, em bytes, da propriedade da classe de dispositivo se a propriedade for recuperada ou o tamanho do buffer necessário se o buffer não for grande o suficiente. Esse ponteiro pode ser definido como NULL.
[in] Flags
Um dos seguintes valores, que especifica se a classe é uma classe de configuração de dispositivo ou 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 definido como NULL. Se MachineName for NULL, SetupDiGetClassPropertyEx recuperará a propriedade de classe de dispositivo solicitada 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
SetupDiGetClassPropertyEx 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 é zero. |
|
A classe de configuração do dispositivo especificada por ClassGuid não é válida. Esse erro só poderá ocorrer se o sinalizador DICLASSPROP_INSTALLER for especificado. |
|
Um parâmetro não especificado não é válido. |
|
A chave de propriedade fornecida por PropertyKey não é válida. |
|
A cadeia de caracteres de referência da interface do dispositivo não é válida. Esse erro poderá ser retornado se o sinalizador DICLASSPROP_INTERFACE for especificado. |
|
Um valor de dados interno não especificado não era válido. |
|
Um buffer de usuário não é válido. Uma possibilidade é que PropertyBuffer seja NULL e PropertyBufferSize não seja zero. |
|
O nome do computador especificado por MachineName não é válido. |
|
A classe de interface do dispositivo especificada por ClassGuid não existe. Esse erro só poderá ocorrer se o sinalizador DICLASSPROP_INTERFACE for especificado. |
|
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. |
|
A propriedade de dispositivo solicitada não existe. |
|
O chamador não tem privilégios de Administrador. |
Comentários
SetupDiGetClassPropertyEx faz parte do modelo de propriedade do dispositivo unificado.
SetupAPI dá suporte apenas a uma versão Unicode de SetupDiGetClassPropertyEx.
Um chamador de SetupDiGetClassPropertyEx deve ser membro do grupo Administradores para definir uma propriedade de interface do dispositivo.
Para obter as chaves de propriedade do dispositivo que representam as propriedades do dispositivo definidas para uma classe de dispositivo em um computador remoto, chame SetupDiGetClassPropertyKeysEx.
Para recuperar uma propriedade de classe de dispositivo em um computador local, chame SetupDiGetClassProperty.
Para definir uma propriedade de classe de dispositivo em um computador local, chame SetupDiSetClassProperty e, para definir uma propriedade de classe de dispositivo em um computador remoto, chame SetupDiSetClassPropertyEx.
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_ExW |
| Cabeçalho | setupapi.h (inclua Setupapi.h) |
| Biblioteca | Setupapi.lib |