SetupDiGetDeviceInterfaceDetailA function (setupapi.h)
The SetupDiGetDeviceInterfaceDetail function returns details about a device interface.
Syntax
WINSETUPAPI BOOL SetupDiGetDeviceInterfaceDetailA(
[in] HDEVINFO DeviceInfoSet,
[in] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
[out, optional] PSP_DEVICE_INTERFACE_DETAIL_DATA_A DeviceInterfaceDetailData,
[in] DWORD DeviceInterfaceDetailDataSize,
[out, optional] PDWORD RequiredSize,
[out, optional] PSP_DEVINFO_DATA DeviceInfoData
);
Parameters
[in] DeviceInfoSet
A pointer to the device information set that contains the interface for which to retrieve details. This handle is typically returned by SetupDiGetClassDevs.
[in] DeviceInterfaceData
A pointer to an SP_DEVICE_INTERFACE_DATA structure that specifies the interface in DeviceInfoSet for which to retrieve details. A pointer of this type is typically returned by SetupDiEnumDeviceInterfaces.
[out, optional] DeviceInterfaceDetailData
A pointer to an SP_DEVICE_INTERFACE_DETAIL_DATA structure to receive information about the specified interface. This parameter is optional and can be NULL. This parameter must be NULL if DeviceInterfaceDetailSize is zero. If this parameter is specified, the caller must set DeviceInterfaceDetailData.cbSize 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.
[in] DeviceInterfaceDetailDataSize
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.
[out, optional] RequiredSize
A pointer to a variable of type DWORD that receives 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. This parameter is optional and can be NULL.
[out, optional] DeviceInfoData
A pointer to a buffer that receives information about the device that supports the requested interface. The caller must set DeviceInfoData.cbSize to sizeof(SP_DEVINFO_DATA). This parameter is optional and can be NULL.
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.
Remarks
Using this function to get details about an interface is typically a two-step process:
- Get the required buffer size. Call SetupDiGetDeviceInterfaceDetail with a NULLDeviceInterfaceDetailData pointer, a 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.
- Allocate an appropriately sized buffer and call the function again to get the interface details.
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.
Note
The setupapi.h header defines SetupDiGetDeviceInterfaceDetail 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 |