Expand Minimize

SetupDiGetCustomDeviceProperty function

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

Syntax


BOOL SetupDiGetCustomDeviceProperty(
  _In_       HDEVINFO DeviceInfoSet,
  _In_       PSP_DEVINFO_DATA DeviceInfoData,
  _In_       PCTSTR CustomPropertyName,
  _In_       DWORD Flags,
  _Out_opt_  PDWORD PropertyRegDataType,
  _Out_      PBYTE PropertyBuffer,
  _In_       DWORD PropertyBufferSize,
  _Out_opt_  PDWORD RequiredSize
);

Parameters

DeviceInfoSet [in]

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.

DeviceInfoData [in]

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

CustomPropertyName [in]

A registry value name representing a custom property.

Flags [in]

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

PropertyRegDataType [out, optional]

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.

PropertyBuffer [out]

A pointer to a buffer that receives requested property information.

PropertyBufferSize [in]

The size, in bytes, of the PropertyBuffer buffer.

RequiredSize [out, optional]

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.

Requirements

Version

Available in Windows XP and later versions of Windows.

Header

Setupapi.h (include Setupapi.h)

Library

Setupapi.lib

See also

SetupDiOpenDevRegKey
SetupDiGetClassRegistryProperty
SetupDiSetClassRegistryProperty
SetupDiGetDeviceRegistryProperty
SetupDiSetDeviceRegistryProperty

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft