Função SetupDiGetDevicePropertyKeys (setupapi.h)

  • Artigo

A função SetupDiGetDevicePropertyKeys recupera uma matriz das chaves de propriedade do dispositivo que representam as propriedades do dispositivo definidas para uma instância do dispositivo.

Sintaxe

WINSETUPAPI BOOL SetupDiGetDevicePropertyKeys(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [out, optional] DEVPROPKEY       *PropertyKeyArray,
  [in]            DWORD            PropertyKeyCount,
  [out, optional] PDWORD           RequiredPropertyKeyCount,
  [in]            DWORD            Flags
);

Parâmetros

[in] DeviceInfoSet

Um identificador para um conjunto de informações do dispositivo. Esse conjunto de informações do dispositivo contém a instância do dispositivo para a qual essa função recupera uma matriz de chaves de propriedade do dispositivo. As chaves de propriedade representam as propriedades do dispositivo definidas para a instância do dispositivo.

[in] DeviceInfoData

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

[out, optional] PropertyKeyArray

Um ponteiro para um buffer que recebe uma matriz de valores do tipo DEVPROPKEY, em que cada valor é uma chave de propriedade do dispositivo que representa uma propriedade de dispositivo definida para a instância do dispositivo. O ponteiro é opcional e pode ser NULL. Para obter mais informações, consulte a seção Comentários mais adiante neste tópico.

[in] PropertyKeyCount

O tamanho, em valores do tipo DEVPROPKEY, do buffer PropertyKeyArray. Se PropertyKeyArray estiver definido como NULL, PropertyKeyCount deverá ser definido como zero.

[out, optional] RequiredPropertyKeyCount

Um ponteiro para uma variável do tipo DWORD que recebe o número de chaves de propriedade do dispositivo solicitadas. O ponteiro é opcional e pode ser definido como NULL.

[in] Flags

Esse parâmetro deve ser definido como zero.

Valor retornado

SetupDiGetDevicePropertyKeys 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_DATA
 Um valor de dados interno não é válido.
ERROR_INVALID_USER_BUFFER
 Um buffer de usuário não é válido. Uma possibilidade é que PropertyKeyArray seja NULL e PropertKeyCount não seja zero.
ERROR_NO_SUCH_DEVINST
 A instância do dispositivo especificada por DevInfoData não existe.
ERROR_INSUFFICIENT_BUFFER
 O buffer PropertyKeyArray é muito pequeno para manter todas as chaves de propriedade solicitadas.
ERROR_NOT_ENOUGH_MEMORY
 Não havia memória do sistema suficiente disponível para concluir a operação.

Comentários

SetupDiGetDevicePropertyKeys faz parte do modelo de propriedade do dispositivo unificado.

Se o buffer ProperKeyArray não for grande o suficiente para manter todas as chaves de propriedade solicitadas, SetupDiGetDevicePropertyKeys não recuperará nenhuma chave de propriedade e retornará ERROR_INSUFFICIENT_BUFFER. Se o chamador forneceu um ponteiro RequiredPropertyKeyCount, SetupDiGetDevicePropertyKeys define o valor de *RequiredPropertyKeyCount para o tamanho necessário, em valores do tipo DEVPROPKEY, do buffer PropertyKeyArray.

Para recuperar uma propriedade de instância de dispositivo, chame SetupDiGetDeviceProperty e, para definir uma propriedade de instância do dispositivo, chame SetupDiSetDeviceProperty.

Requisitos

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

Confira também

SetupDiGetDeviceProperty

SetupDiSetDeviceProperty