SetupDiGetCustomDevicePropertyA function (setupapi.h)

Article
02/09/2023

The SetupDiGetCustomDeviceProperty function retrieves a specified custom device property from the registry.

Syntax

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
);

Parameters

[in] DeviceInfoSet

A handle to the device information set that contains a device information element that represents the device for which to retrieve a custom device property.

[in] DeviceInfoData

A pointer to an SP_DEVINFO_DATA structure that specifies the device information element in DeviceInfoSet.

[in] CustomPropertyName

A registry value name representing a custom property.

[in] Flags

A flag value that indicates how the requested information should be returned. The flag can be zero or one of the following:

DICUSTOMDEVPROP_MERGE_MULTISZ

If set, the function retrieves both device instance-specific property values and hardware ID-specific property values, concatenated as a REG_MULTI_SZ-typed string. (For more information, see the Remarks section on this reference page.)

[out, optional] PropertyRegDataType

A pointer to a variable of type DWORD that receives the data type of the retrieved property. The data type is specified as one of the REG_-prefixed constants that represents registry data types. This parameter is optional and can be NULL.

[out] PropertyBuffer

A pointer to a buffer that receives requested property information.

[in] PropertyBufferSize

The size, in bytes, of the PropertyBuffer buffer.

[out, optional] RequiredSize

A pointer to a variable of type DWORD that receives the buffer size, in bytes, that is required to receive the requested information. This parameter is optional and can be NULL. If this parameter is specified, SetupDiGetCustomDeviceProperty returns the required size, regardless of whether the PropertyBuffer buffer is large enough to receive the requested information.

Return value

If the operation succeeds, SetupDiGetCustomDeviceProperty returns TRUE. Otherwise, the function returns FALSE and the logged error can be retrieved with a call to GetLastError. If the PropertyBuffer buffer is not large enough to receive the requested information, SetupDiGetCustomDeviceProperty returns FALSE and a subsequent call to GetLastError will return ERROR_INSUFFICIENT_BUFFER.

Remarks

SetupDiGetCustomDeviceProperty retrieves device properties that are associated with a single device instance or with all devices matching a certain hardware ID. (For information about hardware IDs, see Device Identification Strings).

Vendors can set properties for a device instance by using INF AddReg directives in INF DDInstall.HW sections and specifying the HKR registry root.

Only the system can set properties for hardware IDs. The system supplies an "Icon" property for some hardware IDs.

The function first checks to see if the specified property exists for the specified device instance. If so, the property's value is returned. If not, the function checks to see if the property exists for all devices matching the hardware ID of the specified device instance. If so, the property's value is returned. If DICUSTOMDEVPROP_MERGE_MULTISZ is set in Flags, the function returns the property values associated with both the device instance and the hardware ID, if they both exist.

Note

The setupapi.h header defines SetupDiGetCustomDeviceProperty as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Available in Windows XP and later versions of Windows.
Target Platform	Desktop
Header	setupapi.h (include Setupapi.h)
Library	Setupapi.lib
DLL	Setupapi.dll

Share via