Função SetupDiSetClassPropertyExW (setupapi.h)
A função SetupDiSetClassPropertyEx define uma propriedade de dispositivo para uma classe de configuração de dispositivo ou uma classe de interface de dispositivo em um computador local ou remoto.
Sintaxe
WINSETUPAPI BOOL SetupDiSetClassPropertyExW(
[in] const GUID *ClassGuid,
[in] const DEVPROPKEY *PropertyKey,
[in] DEVPROPTYPE PropertyType,
[in, optional] const PBYTE PropertyBuffer,
[in] DWORD PropertyBufferSize,
[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 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 da 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 de classe. Para obter mais informações sobre o identificador property-data-type, 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 de classe. Se a propriedade ou o valor da propriedade estiver sendo excluído, esse ponteiro deverá ser definido como NULL e PropertyBufferSize deverá ser definido como zero. Para obter mais informações sobre os requisitos de valor da propriedade, consulte a seção Comentários mais adiante neste tópico.
[in] PropertyBufferSize
O tamanho, em bytes, do buffer PropertyBuffer . O tamanho do buffer de propriedade deve ser consistente com o identificador de tipo de dados de propriedade fornecido pelo PropertyType. 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 de 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 Unicode terminada em NULL que contém o nome UNC, incluindo o prefixo "\", de um computador. Esse ponteiro pode ser definido como NULL. Se o ponteiro for NULL, SetupDiSetClassPropertyEx definirá a propriedade de classe para uma classe instalada no 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
SetupDiSetClassPropertyEx 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 é inválido. |
|
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. |
|
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. |
|
A chave de propriedade fornecida por PropertyKey não é válida. |
|
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 se o valor da propriedade não corresponder ao tipo de propriedade especificado por PropertyType. |
|
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 suficiente do sistema disponível para concluir a operação. |
|
Um item não especificado não foi encontrado. Uma possibilidade é que a propriedade a ser excluída não exista. |
|
O chamador não tem privilégios de Administrador. |
Comentários
SetupDiSetClassPropertyEx faz parte do modelo de propriedade do dispositivo unificado.
SetupAPI dá suporte apenas a uma versão Unicode de SetupDiSetClassPropertyEx.
Um chamador de SetupDiSetClassPropertyEx deve ser um membro do grupo Administradores para definir uma propriedade de interface do dispositivo.
SetupDiSetClassPropertyEx 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 remoto, chame SetupDiGetClassPropertyKeysEx.
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 local, chame SetupDiSetClassProperty.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível no Windows Vista e versões posteriores do Windows. |
| Plataforma de Destino | Área de Trabalho |
| Cabeçalho | setupapi.h (inclua Setupapi.h) |
| Biblioteca | Setupapi.lib |