SetupDiGetDeviceInterfaceDetail

The SetupDiGetDeviceInterfaceDetail function returns details about a particular device interface.

WINSETUPAPI BOOL WINAPI
  SetupDiGetDeviceInterfaceDetail(
    IN HDEVINFO  DeviceInfoSet,
    IN PSP_DEVICE_INTERFACE_DATA  DeviceInterfaceData,
    OUT PSP_DEVICE_INTERFACE_DETAIL_DATA  DeviceInterfaceDetailData,  OPTIONAL
    IN DWORD  DeviceInterfaceDetailDataSize,
    OUT PDWORD  RequiredSize,  OPTIONAL
    OUT PSP_DEVINFO_DATA  DeviceInfoData  OPTIONAL
    );

Parameters

DeviceInfoSet

Pointer to the device information set containing the interface and its underlying device. This handle is typically returned by SetupDiGetClassDevs.

DeviceInterfaceData

Pointer to a SP_DEVICE_INTERFACE_DATA structure that identifies the interface, typically returned by SetupDiEnumDeviceInterfaces.

DeviceInterfaceDetailData

Optionally points to a caller-allocated SP_DEVICE_INTERFACE_DETAIL_DATA structure to receive information about the specified interface. The caller must set DeviceInterfaceDetailData.cbSize to sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA) before calling this function. The cbSize field 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 DeviceInterfaceDetailSize is zero.

DeviceInterfaceDetailDataSize

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 to terminate an empty MULTI_SZ string.

This parameter must be zero if DeviceInterfaceDetailData is NULL.

RequiredSize

Optionally points to a caller-allocated 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

Optionally points to a caller-allocated buffer to receive information about the device that exposes the requested interface. The caller must set DeviceInfoData.cbSize to sizeof(SP_DEVINFO_DATA).

Return Value

SetupDiGetDeviceInterfaceDetail returns TRUE if the function completed without error. If the function completed with an error, FALSE is returned and the error code for the failure can be retrieved by calling GetLastError.

Headers

Declared in setupapi.h. Include setupapi.h.

Comments

Using this 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, an DeviceInterfaceDetailDataSize of zero, and a valid RequiredSize variable. In response to such a call, this function returns the required buffer size at RequiredSize and fails with GetLastError returning ERROR_INSUFFICIENT_BUFFER.
2. Allocate an appropriately sized buffer and call the function again to get the interface details.

The interface detail returned by this function consists of a device path that can be passed to Win32 functions such as CreateFile. Do not attempt to parse the device path symbolic name. The device path can be reused across system boots.

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

See Also

SetupDiEnumDeviceInterfaces, SetupDiGetClassDevs