SetupDiGetDeviceInterfaceAlias

The SetupDiGetDeviceInterfaceAlias function retrieves an alias for the specified device interface. Device interfaces are considered aliases if they are exposed by the same underlying device and have identical reference strings, but are of different interface classes.

BOOL SetupDiGetDeviceInterfaceAlias(
  HDEVINFO DeviceInfoSet,
  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  CONST LPGUID AliasInterfaceClassGuid,
  PSP_DEVICE_INTERFACE_DATA AliasDeviceInterfaceData
);

Parameters

DeviceInfoSet

[in] Pointer to the device information set containing the device interface for which to retrieve an alias. This handle is typically returned by the SetupDiGetClassDevs or SetupDiGetClassDevsEx function.

DeviceInterfaceData

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

AliasInterfaceClassGuid

[in] A class GUID specifying the interface class of the alias to retrieve.

AliasDeviceInterfaceData

[out] Pointer to a buffer that contains, on successful return, a completed SP_DEVICE_INTERFACE_DATA structure that identifies the requested alias. You must set the cbSize member to sizeof(SP_DEVICE_INTERFACE_DATA) before calling this function.

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. Possible errors returned by GetLastError include the following.

Remarks

The SetupDiGetDeviceInterfaceAlias function can be used to locate a device that exposes more than one interface. For example, consider a disk that can be part of a fault-tolerant volume and can contain encrypted data. The function driver for the disk device could register a fault-tolerant-volume interface and an encrypted-volume interface. These interfaces are device interface aliases if the function driver registers them with identical reference strings and they refer to the same device.

To locate a device with multiple interfaces, perform the following steps

1. Locate all available devices of a particular class by using the SetupDiGetClassDevs or SetupDiGetClassDevsEx function.
2. Determine which of these devices expose one of the interfaces by using the SetupDiEnumDeviceInterfaces function.
3. Pass a device that exposes the first interface to SetupDiGetDeviceInterfaceAlias and request an alias for the other interface class.

If the requested alias exists but the AliasDeviceInterfaceData buffer is invalid, this function successfully adds the device interface to the device information set, but returns FALSE. In this case, GetLastError returns ERROR_INVALID_USER_BUFFER.

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