Função SetupDiSetClassPropertyW (setupapi.h)

Artigo
08/26/2023

A função SetupDiSetClassProperty define uma propriedade de classe para uma classe de configuração de dispositivo ou uma classe de interface do dispositivo.

Sintaxe

WINSETUPAPI BOOL SetupDiSetClassPropertyW(
  [in]           const GUID       *ClassGuid,
  [in]           const DEVPROPKEY *PropertyKey,
  [in]           DEVPROPTYPE      PropertyType,
  [in, optional] const PBYTE      PropertyBuffer,
  [in]           DWORD            PropertyBufferSize,
  [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 definir uma propriedade 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 a ser definida.

[in] PropertyType

Um valor do tipo DEVPROPTYPE que representa o identificador de tipo de dados de propriedade para a propriedade da classe de dispositivo. Para obter mais informações sobre o identificador de tipo de dados de propriedade, consulte a seção Comentários mais adiante neste tópico.

[in, optional] PropertyBuffer

Um ponteiro para um buffer que contém o valor da propriedade da classe de dispositivo. Se a propriedade ou os dados estiverem sendo excluídos, esse ponteiro deverá ser definido como NULL e PropertyBufferSize deverá ser definido como zero. Para obter mais informações sobre dados de propriedade, consulte a seção Comentários mais adiante neste tópico.

[in] PropertyBufferSize

O tamanho, em bytes, do buffer PropertyBuffer . Se PropertyBuffer estiver definido como NULL, PropertyBufferSize deverá ser definido como zero.

[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.

Retornar valor

SetupDiSetClassProperty 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 é inválido.
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_REFERENCE_STRING	A cadeia de caracteres de referência da interface do dispositivo não é válida. Esse erro só poderá ocorrer se o sinalizador DICLASSPROP_INTERFACE for especificado.
ERROR_INVALID_REG_PROPERTY	A chave de propriedade fornecida por PropertyKey não é válida.
ERROR_INVALID_DATA	Um valor de dados interno não especificado não era válido. Esse erro poderá ser registrado se o valor ClassGuid não for um GUID válido ou o valor da propriedade não for consistente com o tipo de propriedade especificado por PropertyType.
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	Um item não especificado não foi encontrado. Uma possibilidade é que a propriedade a ser excluída não exista.
ERROR_ACCESS_DENIED	O chamador não tem privilégios de Administrador.

Comentários

SetupDiSetClassProperty faz parte do modelo de propriedade do dispositivo unificado.

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

Um chamador de SetupDiSetClassProperty deve ser membro do grupo Administradores para definir uma propriedade de interface do dispositivo.

SetupDiSetClassProperty impõe requisitos no identificador de tipo de dados de propriedade e no valor da propriedade.

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 local, chame SetupDiGetClassProperty e 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 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_Set_Class_Property
Cabeçalho	setupapi.h (inclua Setupapi.h)
Biblioteca	Setupapi.lib