Função SetupDiGetDevicePropertyW (setupapi.h)

  • Artigo

A função SetupDiGetDeviceProperty recupera uma propriedade de instância do dispositivo.

Sintaxe

WINSETUPAPI BOOL SetupDiGetDevicePropertyW(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            const DEVPROPKEY *PropertyKey,
  [out]           DEVPROPTYPE      *PropertyType,
  [out, optional] PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize,
  [in]            DWORD            Flags
);

Parâmetros

[in] DeviceInfoSet

Um identificador para um conjunto de informações do dispositivo que contém uma instância de dispositivo para a qual recuperar uma propriedade de instância de dispositivo.

[in] DeviceInfoData

Um ponteiro para a estrutura SP_DEVINFO_DATA que representa a instância do dispositivo para a qual recuperar uma propriedade de instância de dispositivo.

[in] PropertyKey

Um ponteiro para uma estrutura DEVPROPKEY que representa a chave de propriedade do dispositivo da propriedade de instância do dispositivo solicitada.

[out] PropertyType

Um ponteiro para uma variável do tipo DEVPROPTYPE que recebe o identificador property-data-type da propriedade de instância do 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 instância de dispositivo solicitada. SetupDiGetDeviceProperty recupera a 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 for definido como NULL e RequiredSize for fornecido, SetupDiGetDeviceProperty retornará o tamanho da propriedade, 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 instância do 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

Esse parâmetro deve ser definido como zero.

Retornar valor

SetupDiGetDeviceProperty 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_HANDLE
 O conjunto de informações do dispositivo especificado por DevInfoSet não é válido.
ERROR_INVALID_PARAMETER
 Um parâmetro fornecido não é válido. Uma possibilidade é que o elemento de informações do dispositivo não seja válido.
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.
ERROR_INVALID_USER_BUFFER
 Um buffer de usuário não é válido. Uma possibilidade é que PropertyBuffer seja NULL e PropertBufferSize não seja zero.
ERROR_NO_SUCH_DEVINST
 A instância do dispositivo especificada por DevInfoData não existe.
ERROR_INSUFFICIENT_BUFFER
 O buffer PropertyBuffer é muito pequeno para conter o valor da propriedade solicitada ou 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 suficiente do sistema 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

SetupDiGetDeviceProperty faz parte do modelo de propriedade do dispositivo unificado.

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

Para obter as chaves de propriedade do dispositivo que representam as propriedades do dispositivo definidas para uma instância de dispositivo, chame SetupDiGetDevicePropertyKeys.

Para definir uma propriedade de instância de dispositivo, chame SetupDiSetDeviceProperty.

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_DevNode_Property
Cabeçalho setupapi.h (inclua SetupAPI.h)
Biblioteca SetupAPI.lib
DLL SetupAPI.dll
Conjunto de APIs ext-ms-win-setupapi-classinstallers-l1-1-0 (introduzido no Windows 8)

Confira também

SetupDiGetDevicePropertyKeys

SetupDiSetDeviceProperty