SetupDiGetDeviceInstanceIdA function (setupapi.h)

The SetupDiGetDeviceInstanceId function retrieves the device instance ID that is associated with a device information element.

Note

In Windows Vista and later versions of Windows, the unified device property model uses the DEVPKEY_Device_InstanceId property key to represent the device instance identifier. See Retrieving a Device Instance Identifier for details.

Syntax

WINSETUPAPI BOOL SetupDiGetDeviceInstanceIdA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [out, optional] PSTR             DeviceInstanceId,
  [in]            DWORD            DeviceInstanceIdSize,
  [out, optional] PDWORD           RequiredSize
);

Parameters

[in] DeviceInfoSet

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

[in] DeviceInfoData

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

[out, optional] DeviceInstanceId

A pointer to the character buffer that will receive the NULL-terminated device instance ID for the specified device information element. For information about device instance IDs, see Device Identification Strings.

[in] DeviceInstanceIdSize

The size, in characters, of the DeviceInstanceId buffer.

[out, optional] RequiredSize

A pointer to the variable that receives the number of characters required to store the device instance ID.

Return value

The function returns TRUE if it is successful. Otherwise, it returns FALSE and the logged error can be retrieved by making a call to GetLastError.

Remarks

Note

The setupapi.h header defines SetupDiGetDeviceInstanceId 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 Microsoft Windows 2000 and later versions of Windows.
Target Platform Desktop
Header setupapi.h (include Setupapi.h)
Library Setupapi.lib

See also

SP_DEVINFO_DATA

SetupDiCreateDevRegKey

SetupDiCreateDeviceInfo

SetupDiOpenDevRegKey

SetupDiOpenDeviceInfo