SetupDiGetDeviceInterfaceDetail

The SetupDiGetDeviceInterfaceDetail function retrieves detailed information about a specified device interface.

BOOL SetupDiGetDeviceInterfaceDetail(
  HDEVINFO DeviceInfoSet,
  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  PSP_DEVICE_INTERFACE_DETAIL_DATA DeviceInterfaceDetailData, 
  DWORD DeviceInterfaceDetailDataSize,
  PDWORD RequiredSize, 
  PSP_DEVINFO_DATA DeviceInfoData 
);

Parameters

DeviceInfoSet

[in] Pointer to the device information set that contains the interface and its underlying device. This handle is typically returned by the SetupDiGetClassDevs or SetupDiGetClassDevsEx function.

DeviceInterfaceData

[in] Pointer to an SP_DEVICE_INTERFACE_DATA structure that identifies the interface. This structure is typically returned by the SetupDiEnumDeviceInterfaces function.

DeviceInterfaceDetailData

[out] An optional pointer to a SP_DEVICE_INTERFACE_DETAIL_DATA structure to receive information about the specified interface. You must set the cbSize member to sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA) before calling this function. The cbSize member always contains the size of the fixed part of the data structure, not a size reflecting the variable-length string at the end.

This parameter must be NULL if the DeviceInterfaceDetailSize parameter is zero.

DeviceInterfaceDetailDataSize

[in] Specifies the size of the DeviceInterfaceDetailData buffer. The buffer must be at least (offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + sizeof(TCHAR)) bytes, to contain the fixed part of the structure and a single NULL character to terminate an empty MULTI_SZ string.

This parameter must be zero if DeviceInterfaceDetailData is NULL.

RequiredSize

[out] An optional pointer to a variable to receive the required size of the DeviceInterfaceDetailData buffer. This size includes the size of the fixed part of the structure plus the number of bytes required for the variable-length device path string.

DeviceInfoData

[out] An optional pointer to an SP_DEVINFO_DATA structure to receive information about the device that exposes the requested interface. You must set the cbSize member to sizeof(SP_DEVINFO_DATA).

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Using the SetupDiGetDeviceInterfaceDetail function to get details about an interface is typically a two-step process:

1. Get the required buffer size. Call SetupDiGetDeviceInterfaceDetail with a NULL DeviceInterfaceDetailData pointer, a DeviceInterfaceDetailDataSize of zero, and a valid RequiredSize variable. In response to such a call, this function fails, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and the RequiredSize parameter receives the required buffer size.
2. Allocate an appropriately sized buffer and call the function again to get the interface details.

The interface details returned by this function include a device path that can be passed to Win32 functions such as CreateFile. Do not attempt to parse the device path symbolic name. Note that the device path can be reused after the system is rebooted.

The SetupDiGetDeviceInterfaceDetail function can be used to get only the DeviceInfoData parameter. If the interface exists but the DeviceInterfaceDetailData parameter is NULL, the function fails, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and the DeviceInfoData structure is filled with information about the device that exposes the interface.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 98.
  Header: Declared in Setupapi.h.
  Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiEnumDeviceInterfaces, SetupDiGetClassDevs, SetupDiGetClassDevsEx, SP_DEVICE_INTERFACE_DATA, SP_DEVICE_INTERFACE_DETAIL_DATA, SP_DEVINFO_DATA