Função SetupDiGetDeviceInterfacePropertyW (setupapi.h)

  • Artigo

A função SetupDiGetDeviceInterfaceProperty recupera uma propriedade de dispositivo definida para uma interface do dispositivo.

Sintaxe

WINSETUPAPI BOOL SetupDiGetDeviceInterfacePropertyW(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  [in]            const DEVPROPKEY          *PropertyKey,
  [out]           DEVPROPTYPE               *PropertyType,
  [out]           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 interface do dispositivo para a qual recuperar uma propriedade de interface do dispositivo.

[in] DeviceInterfaceData

Um ponteiro para uma estrutura SP_DEVICE_INTERFACE_DATA que representa a interface do dispositivo para a qual recuperar uma propriedade de interface do dispositivo.

[in] PropertyKey

Um ponteiro para uma estrutura DEVPROPKEY que representa a chave de propriedade da interface do dispositivo da propriedade de interface do dispositivo a ser recuperada.

[out] PropertyType

Um ponteiro para uma variável do tipo DEVPROPTYPE que recebe o identificador property-data-type da propriedade de interface do dispositivo solicitada. O identificador de tipo de dados de propriedade é um 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 interface do dispositivo solicitada. SetupDiGetDeviceInterfaceProperty 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 estiver definido como NULL e RequiredSize for fornecido, SetupDiGetDeviceInterfaceProperty 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 de interface 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

SetupDiGetDeviceInterfaceProperty 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. Outros códigos de erro podem ser definidos pelas funções do instalador de dispositivo que são chamadas por essa API.

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 a interface do dispositivo especificada por DeviceInterfaceData não seja válida.
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 PropertyBufferSize não seja zero.
ERROR_NO_SUCH_DEVICE_INTERFACE
 A interface do dispositivo especificada por DeviceInterfaceData não existe.
ERROR_INSUFFICIENT_BUFFER
 O buffer PropertyBuffer não é grande o suficiente para manter o valor da propriedade 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 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

SetupDiGetDeviceInterfaceProperty faz parte do modelo de propriedade do dispositivo unificado.

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

Um chamador de SetupDiGetDeviceInterfaceProperty 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 interface do dispositivo, chame SetupDiGetDeviceInterfacePropertyKeys.

Para definir uma propriedade de interface do dispositivo, chame SetupDiSetDeviceInterfaceProperty.

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

Confira também

SetupDiGetDeviceInterfacePropertyKeys

SetupDiSetDeviceInterfaceProperty