Função SetupDiGetClassPropertyW (setupapi.h)

Artigo
03/15/2023

A função SetupDiGetClassProperty recupera uma propriedade de dispositivo definida para uma classe de configuração de dispositivo ou uma classe de interface do dispositivo.

Sintaxe

WINSETUPAPI BOOL SetupDiGetClassPropertyW(
  [in]            const GUID       *ClassGuid,
  [in]            const DEVPROPKEY *PropertyKey,
  [out]           DEVPROPTYPE      *PropertyType,
  [out]           PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize,
  [in]            DWORD            Flags
);

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 definida 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] PropertyBuffer

Um ponteiro para um buffer que recebe a propriedade de classe de dispositivo solicitada. SetupDiGetClassProperty 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, SetupDiGetClassProperty 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 da classe de dispositivo 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 valores a seguir, 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.

Retornar valor

SetupDiGetClassProperty 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
ERROR_INVALID_FLAGS	O valor de Flags não é zero.
ERROR_INVALID_CLASS	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.
ERROR_INVALID_PARAMETER	Um parâmetro não especificado não é válido.
ERROR_INVALID_REG_PROPERTY	A chave de propriedade fornecida por PropertyKey não é válida.
ERROR_INVALID_REFERENCE_STRING	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.
ERROR_INVALID_DATA	Um valor de dados interno não especificado não era válido.
ERROR_INVALID_USER_BUFFER	Um buffer de usuário não é válido. Uma possibilidade é que PropertyBuffer seja NULL e PropertyBufferSize não seja zero.
ERROR_NO_SUCH_INTERFACE_CLASS	A classe de interface do dispositivo especificada por ClassGuid não existe. Esse erro só poderá ocorrer se o sinalizador DICLASSPROP_INTERFACE for especificado.
ERROR_INSUFFICIENT_BUFFER	Um buffer de dados interno que foi passado para uma chamada do sistema era muito pequeno.
ERROR_NOT_ENOUGH_MEMORY	Não havia memória do sistema suficiente disponível para concluir a operação.
ERROR_NOT_FOUND	A propriedade de dispositivo solicitada não existe.
ERROR_ACCESS_DENIED	O chamador não tem privilégios de Administrador.

Comentários

SetupDiGetClassProperty faz parte do modelo de propriedade do dispositivo unificado.

SetupAPI dá suporte apenas a uma versão Unicode de SetupDiGetClassProperty.

Um chamador de SetupDiGetClassProperty 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 local, chame SetupDiGetClassPropertyKeys.

Para recuperar uma propriedade de classe de dispositivo em um computador remoto, chame SetupDiGetClassPropertyEx.

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
Cabeçalho	setupapi.h (inclua Setupapi.h)
Biblioteca	Setupapi.lib