Função SetupDiGetCustomDevicePropertyA (setupapi.h)

Artigo
08/26/2023

A função SetupDiGetCustomDeviceProperty recupera uma propriedade de dispositivo personalizada especificada do registro.

Sintaxe

WINSETUPAPI BOOL SetupDiGetCustomDevicePropertyA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            PCSTR            CustomPropertyName,
  [in]            DWORD            Flags,
  [out, optional] PDWORD           PropertyRegDataType,
  [out]           PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize
);

Parâmetros

[in] DeviceInfoSet

Um identificador para o conjunto de informações do dispositivo que contém um elemento de informações do dispositivo que representa o dispositivo para o qual recuperar uma propriedade de dispositivo personalizada.

[in] DeviceInfoData

Um ponteiro para uma estrutura SP_DEVINFO_DATA que especifica o elemento de informações do dispositivo em DeviceInfoSet.

[in] CustomPropertyName

Um nome de valor do Registro que representa uma propriedade personalizada.

[in] Flags

Um valor de sinalizador que indica como as informações solicitadas devem ser retornadas. O sinalizador pode ser zero ou um dos seguintes:

DICUSTOMDEVPROP_MERGE_MULTISZ

Se definida, a função recuperará valores de propriedade específicos da instância do dispositivo e valores de propriedade específicos da ID de hardware, concatenados como uma cadeia de caracteres do tipo REG_MULTI_SZ. (Para obter mais informações, consulte a seção Comentários nesta página de referência.)

[out, optional] PropertyRegDataType

Um ponteiro para uma variável do tipo DWORD que recebe o tipo de dados da propriedade recuperada. O tipo de dados é especificado como uma das constantes prefixadas por REG_ que representa os tipos de dados do Registro. Esse parâmetro é opcional e pode ser NULL.

[out] PropertyBuffer

Um ponteiro para um buffer que recebe informações de propriedade solicitadas.

[in] PropertyBufferSize

O tamanho, em bytes, do buffer PropertyBuffer .

[out, optional] RequiredSize

Um ponteiro para uma variável do tipo DWORD que recebe o tamanho do buffer, em bytes, que é necessário para receber as informações solicitadas. Esse parâmetro é opcional e pode ser NULL. Se esse parâmetro for especificado, SetupDiGetCustomDeviceProperty retornará o tamanho necessário, independentemente de o buffer PropertyBuffer ser grande o suficiente para receber as informações solicitadas.

Retornar valor

Se a operação for bem-sucedida, SetupDiGetCustomDeviceProperty retornará TRUE. Caso contrário, a função retornará FALSE e o erro registrado poderá ser recuperado com uma chamada para GetLastError. Se o buffer PropertyBuffer não for grande o suficiente para receber as informações solicitadas, SetupDiGetCustomDeviceProperty retornará FALSE e uma chamada subsequente para GetLastError retornará ERROR_INSUFFICIENT_BUFFER.

Comentários

SetupDiGetCustomDeviceProperty recupera as propriedades do dispositivo associadas a uma única instância de dispositivo ou a todos os dispositivos que correspondem a uma determinada ID de hardware. (Para obter informações sobre IDs de hardware, consulte Cadeias de caracteres de identificação do dispositivo).

Os fornecedores podem definir propriedades para uma instância de dispositivo usando diretivas INF AddReg nas seções INF DDInstall.HW e especificando a raiz do registro HKR .

Somente o sistema pode definir propriedades para IDs de hardware. O sistema fornece uma propriedade "Icon" para algumas IDs de hardware.

A função primeiro verifica se a propriedade especificada existe para a instância de dispositivo especificada. Nesse caso, o valor da propriedade é retornado. Caso contrário, a função verifica se a propriedade existe para todos os dispositivos que correspondem à ID de hardware da instância de dispositivo especificada. Nesse caso, o valor da propriedade é retornado. Se DICUSTOMDEVPROP_MERGE_MULTISZ estiver definido em Sinalizadores, a função retornará os valores de propriedade associados à instância do dispositivo e à ID de hardware, se ambos existirem.

Observação

O cabeçalho setupapi.h define SetupDiGetCustomDeviceProperty como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows XP e versões posteriores do Windows.
Plataforma de Destino	Área de Trabalho
Cabeçalho	setupapi.h (inclua Setupapi.h)
Biblioteca	Setupapi.lib
DLL	Setupapi.dll