Expand Minimize

SetupDiGetDeviceInterfaceAlias function

The SetupDiGetDeviceInterfaceAlias function returns an alias of a specified device interface.

Syntax


BOOL SetupDiGetDeviceInterfaceAlias(
  _In_   HDEVINFO DeviceInfoSet,
  _In_   PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  _In_   const GUID *AliasInterfaceClassGuid,
  _Out_  PSP_DEVICE_INTERFACE_DATA AliasDeviceInterfaceData
);

Parameters

DeviceInfoSet [in]

A pointer to the device information set that contains the device interface for which to retrieve an alias. This handle is typically returned by SetupDiGetClassDevs.

DeviceInterfaceData [in]

A pointer to an SP_DEVICE_INTERFACE_DATA structure that specifies the device interface in DeviceInfoSet for which to retrieve an alias. This pointer is typically returned by SetupDiEnumDeviceInterfaces.

AliasInterfaceClassGuid [in]

A pointer to a GUID that specifies the interface class of the alias to retrieve.

AliasDeviceInterfaceData [out]

A pointer to a caller-allocated buffer that contains, on successful return, a completed SP_DEVICE_INTERFACE_DATA structure that identifies the requested alias. The caller must set AliasDeviceInterfaceData.cbSize to sizeof(SP_DEVICE_INTERFACE_DATA) before calling this function.

Return value

SetupDiGetDeviceInterfaceAlias 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.

Possible errors returned by GetLastError are listed in the following table.

Return codeDescription
ERROR_INVALID_PARAMETER

Invalid DeviceInfoSet or invalid DeviceInterfaceData parameter.

ERROR_NO_SUCH_INTERFACE_DEVICE

There is no alias of class AliasInterfaceClassGuid for the specified device interface.

ERROR_INVALID_USER_BUFFER

Invalid AliasDeviceInterfaceData buffer.

 

Remarks

Device interfaces are considered aliases if they are of different interface classes but are supported by the same device and have identical reference strings.

SetupDiGetDeviceInterfaceAlias 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. (The reference strings will likely be NULL and therefore are equal.)

To locate such a multi-interface device, first locate all available devices that expose one of the interfaces, such as the fault-tolerant-volume interface, using SetupDiGetClassDevs and SetupDiEnumDeviceInterfaces. Then, pass a device with the first interface (fault-tolerant-volume) to SetupDiGetDeviceInterfaceAlias and request an alias of the other interface class (encrypted-volume).

If the requested alias exists but the caller-supplied AliasDeviceInterfaceData buffer is invalid, this function successfully adds the device interface element to DevInfoSet but returns FALSE for the return value. In this case, GetLastError returns ERROR_INVALID_USER_BUFFER.

Requirements

Version

Available in Microsoft Windows 2000 and later versions of Windows.

Header

Setupapi.h (include Setupapi.h)

Library

Setupapi.lib

See also

SetupDiEnumDeviceInterfaces
SetupDiGetClassDevs

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft