SetupDiGetDeviceInterfaceAlias 函数 (setupapi.h)

  • 项目

SetupDiGetDeviceInterfaceAlias 函数返回指定设备接口的别名。

语法

WINSETUPAPI BOOL SetupDiGetDeviceInterfaceAlias(
  [in]  HDEVINFO                  DeviceInfoSet,
  [in]  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  [in]  const GUID                *AliasInterfaceClassGuid,
  [out] PSP_DEVICE_INTERFACE_DATA AliasDeviceInterfaceData
);

参数

[in] DeviceInfoSet

指向 设备信息集 的指针，该信息集包含要为其检索别名的设备接口。 此句柄通常由 SetupDiGetClassDevs 返回。

[in] DeviceInterfaceData

指向 SP_DEVICE_INTERFACE_DATA 结构的指针，该结构指定要在 DeviceInfoSet 中检索别名的设备接口。 此指针通常由 SetupDiEnumDeviceInterfaces 返回。

[in] AliasInterfaceClassGuid

指向 GUID 的指针，指定要检索的别名的接口类。

[out] AliasDeviceInterfaceData

指向调用方分配的缓冲区的指针，该缓冲区在成功返回时包含标识所请求别名的已完成 SP_DEVICE_INTERFACE_DATA 结构。 调用方必须在调用此函数之前将 AliasDeviceInterfaceData.cbSize 设置为 sizeof (SP_DEVICE_INTERFACE_DATA) 。

返回值

如果函数完成且未出错，SetupDiGetDeviceInterfaceAlias 将返回 TRUE。 如果函数完成时出现错误，则返回 FALSE ，并且可以通过调用 GetLastError 来检索失败的错误代码。

下表列出了 GetLastError 返回的可能错误。

返回代码 说明
ERROR_INVALID_PARAMETER
 无效的 DeviceInfoSet 或无效的 DeviceInterfaceData 参数。
ERROR_NO_SUCH_INTERFACE_DEVICE
 对于指定的设备接口， 没有 AliasInterfaceClassGuid 类的别名。
ERROR_INVALID_USER_BUFFER
 AliasDeviceInterfaceData 缓冲区无效。

注解

如果设备接口属于不同的接口类，但受同一设备支持且具有相同的引用字符串，则它们被视为别名。

SetupDiGetDeviceInterfaceAlias 可用于查找公开多个接口的设备。 例如，请考虑一个磁盘，该磁盘可以是容错卷的一部分，并且可以包含加密数据。 磁盘设备的函数驱动程序可以注册容错卷接口和加密卷接口。 如果函数驱动程序使用相同的引用字符串注册这些接口，并且它们引用同一设备，则这些接口是设备接口别名。 (引用字符串可能为 NULL ，因此相等。)

若要查找此类多接口设备，请先使用 SetupDiGetClassDevs 和 SetupDiEnumDeviceInterfaces 找到公开其中一个接口的所有可用设备，例如容错卷接口。 然后，将具有第一个接口 (容错卷) 的设备传递到 SetupDiGetDeviceInterfaceAlias ，并请求另一个接口类的别名 (encrypted-volume) 。

如果请求的别名存在，但调用方提供的 AliasDeviceInterfaceData 缓冲区无效，则此函数会将设备接口元素成功添加到 DevInfoSet ，但返回值返回 FALSE 。 在这种情况下， GetLastError 返回ERROR_INVALID_USER_BUFFER。

要求

要求 值
最低受支持的客户端 在 Microsoft Windows 2000 及更高版本的 Windows 中可用。
目标平台 桌面
标头 setupapi.h (包括 Setupapi.h)
Library Setupapi.lib
DLL Setupapi.dll

另请参阅

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs