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 傳回的可能錯誤。

傳回碼 Description
ERROR_INVALID_PARAMETER
 無效的 DeviceInfoSet 或無效的 DeviceInterfaceData 參數。
ERROR_NO_SUCH_INTERFACE_DEVICE
 指定的裝置介面沒有 AliasInterfaceClassGuid 類別的別名。
ERROR_INVALID_USER_BUFFER
 無效 的 AliasDeviceInterfaceData 緩衝區。

備註

如果裝置介面屬於不同的介面類別，但由相同裝置支援，而且具有相同的參考字串，則裝置介面會被視為別名。

SetupDiGetDeviceInterfaceAlias 可用來尋找公開多個介面的裝置。 例如，假設磁碟可以是容錯磁碟區的一部分，而且可以包含加密的數據。 磁碟裝置的函式驅動程式可以註冊容錯磁碟區介面和加密磁碟區介面。 如果函式驅動程式以相同的參考字串註冊這些介面，而且它們參考相同的裝置，這些介面就是裝置介面就是裝置介面別名。 (參考字串可能為 NULL ，因此相等。)

若要找出這類多介面裝置，請先找出公開其中一個介面的所有可用裝置，例如容錯磁碟區介面，使用 SetupDiGetClassDevs 和 SetupDiEnumDeviceInterfaces。 然後，將具有第一個介面的裝置 (容錯磁碟區) 傳遞至 SetupDiGetDeviceInterfaceAlias ，並要求另一個介面類別的別名 (加密磁碟區) 。

如果要求的別名存在，但呼叫端提供的 AliasDeviceInterfaceData 緩衝區無效，此函式會成功將裝置介面元素新增至 DevInfoSet ，但傳回值會傳回 FALSE 。 在此情況下， GetLastError 會傳回ERROR_INVALID_USER_BUFFER。

規格需求

需求 值
最低支援的用戶端 可在 Microsoft Windows 2000 和更新版本的 Windows 中使用。
目標平台 桌面
標頭 setupapi.h (包括 Setupapi.h)
程式庫 Setupapi.lib
Dll Setupapi.dll

另請參閱

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs