Função SetupDiGetClassPropertyExW (setupapi.h)

Artigo
03/15/2023

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
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_INVALID_MACHINENAME	O nome do computador especificado por MachineName não é válido.
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

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