Share via

SetupDiOpenDeviceInterfaceA 函式 (setupapi.h)

  • 發行項

SetupDiOpenDeviceInterface 函式會擷取裝置介面的相關信息，並將介面新增至本機系統或遠端系統所設定的指定裝置資訊。

語法

WINSETUPAPI BOOL SetupDiOpenDeviceInterfaceA(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PCSTR                     DevicePath,
  [in]            DWORD                     OpenFlags,
  [out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

參數

[in] DeviceInfoSet

包含或將包含之 裝置資訊集 的指標，代表支援開啟介面之裝置的裝置信息專案。

[in] DevicePath

NULL 終止字串的指標，提供要開啟之裝置介面的名稱。 此名稱是 Win32 裝置路徑，通常是在 PnP 通知結構中接收，或是先前呼叫 SetupDiEnumDeviceInterfaces 及其相關函式所取得。

[in] OpenFlags

旗標，決定如何開啟裝置介面專案。 唯一有效的旗標如下：

DIODI_NO_ADD

指定如果指定的 裝置資訊集中尚未存在該元素，將不會建立基礎裝置的裝置信息專案。 如需詳細資訊，請參閱下列一節。

[out, optional] DeviceInterfaceData

呼叫端初始化 SP_DEVICE_INTERFACE_DATA 結構的指標，可接收要求的介面數據。 此指標是選擇性的，而且可以是 NULL。 如果提供緩衝區，呼叫端必須先將 結構的 cbSize 成員設定為 sizeof (SP_DEVICE_INTERFACE_DATA ) ，才能呼叫 SetupDiOpenDeviceInterface。 如需詳細資訊，請參閱下列一節。

傳回值

如果函式未發生錯誤，SetupDiOpenDeviceInterface 會傳回 TRUE。 如果函式已完成錯誤，它會傳回 FALSE ，而且呼叫 GetLastError 即可擷取失敗的錯誤碼。

備註

如果 DeviceInfoSet 中已有介面的裝置介面元素， SetupDiOpenDeviceInterface 會更新旗標。 因此，此函式可用來更新裝置介面的旗標。 例如，介面在初次開啟時可能處於非作用中狀態，但後續會變成作用中。 如果基礎裝置的裝置資訊元素尚未出現在 DeviceInfoSet 中，此函式會建立一個，並將它新增至 DeviceInfoSet。

如果函式成功開啟新的裝置介面，但呼叫端未在 DeviceInterfaceData 參數中提供有效的結構，則函式會傳回 FALSE ，且 後續呼叫 GetLastError 會傳回ERROR_INVALID_USER_BUFFER。 不過，在此情況下， SetupDiOpenDeviceInterface 會將要求的介面新增至裝置資訊集。

如果成功開啟新的裝置介面，但呼叫端提供的 DeviceInterfaceData 緩衝區無效，則此函式會傳回 FALSE ，而 GetLastError 會傳回ERROR_INVALID_USER_BUFFER。 呼叫端的緩衝區錯誤不會防止開啟介面。

如果已為 OpenFlags 參數指定DIODI_NO_ADD旗標，且基礎裝置的裝置資訊元素尚未出現在指定的 裝置資訊集中，則此函式會傳回 FALSE ，而 GetLastError 會傳回ERROR_NO_SUCH_DEVICE_INTERFACE。

當應用程式使用 SetupDiOpenDeviceInterface 擷取的資訊完成時， 應用程式必須呼叫 SetupDiDeleteDeviceInterfaceData。

MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK屬性可以當做 SetupDiOpenDeviceInterface 函式的 DevicePath 自變數值傳入。

注意

setupapi.h 標頭會將 SetupDiOpenDeviceInterface 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

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

另請參閱

SetupDiDeleteDeviceInterfaceData

SetupDiEnumDeviceInterfaces