WlanSetProfileEapXmlUserData 函式 (wlanapi.h)

發行項
03/04/2024

WlanSetProfileEapXmlUserData 函式會設定可延伸驗證通訊協定 (EAP) XML 字串所指定的用戶認證。使用者認證會套用至配接器上的配置檔。這些認證只能由呼叫端使用。

語法

DWORD WlanSetProfileEapXmlUserData(
  [in] HANDLE     hClientHandle,
  [in] const GUID *pInterfaceGuid,
  [in] LPCWSTR    strProfileName,
  [in] DWORD      dwFlags,
  [in] LPCWSTR    strEapXmlUserData,
       PVOID      pReserved
);

參數

[in] hClientHandle

用戶端的會話句柄，由先前呼叫 WlanOpenHandle 函式取得。

[in] pInterfaceGuid

介面的 GUID。

[in] strProfileName

與EAP用戶數據相關聯的配置檔名稱。配置檔名稱會區分大小寫。此字串必須以 NULL 結束。

Windows XP 搭配 SP3 和適用於 Windows XP 的無線 LAN API 與 SP2： 提供的名稱必須符合從網路的 SSID 自動衍生的設定檔名稱。針對基礎結構網路配置檔，必須針對配置檔名稱提供 SSID。針對臨機操作網路配置檔，提供的名稱必須是臨機操作網路的 SSID，後面接著 -adhoc。

[in] dwFlags

一組旗標，可修改函式的行為。

在具有SP2、Windows XP SP3、Windows Vista 和 Windows Server 2008 的 Windows XP 無線 LAN API 上，此參數是保留的，且應設定為零。

在 Windows 7、Windows Server 2008 R2 和更新版本上，此參數可以是下列其中一個值。

值	意義
WLAN_SET_EAPHOST_DATA_ALL_USERS 0x00000001	設定此設定檔所有使用者的 EAP 主機數據。

[in] strEapXmlUserData

用來設定使用者認證的 XML 資料的指標。

XML 數據必須以 EAPHost 使用者認證架構為基礎。若要檢視範例使用者認證 XML 數據，請參閱 EAPHost 用戶屬性。

pReserved

保留供未來使用。必須設定為 NULL。

傳回值

如果函式成功，傳回值會ERROR_SUCCESS。

如果函式失敗，傳回值可能是下列其中一個傳回碼。

傳回碼	Description
ERROR_ACCESS_DENIED	存取遭到拒絕。如果呼叫端沒有配置檔的寫入許可權，就會傳回此值。
ERROR_BAD_PROFILE	網路連線配置檔已損毀。如果無法剖析 strProfileName 參數中指定的配置檔，就會傳回此錯誤。
ERROR_INVALID_PARAMETER	參數不正確。如果發生下列任一情況，就會傳回此值： hClientHandle 為 NULL。 pInterfaceGuid 為 NULL。 strProfileName 為 NULL。 strEapXmlUserData 為 NULL。 pReserved 不是 NULL。
ERROR_INVALID_HANDLE	句柄無效。如果在句柄數據表中找不到句柄 hClientHandle ，就會傳回此錯誤。
ERROR_NOT_ENOUGH_MEMORY	沒有足夠的記憶體可用來處理此命令。
ERROR_NOT_SUPPORTED	不支援此要求。當設定檔設定不允許儲存用戶數據時，就會傳回此值。啟用單一登錄 (SSO) 時，可能會發生這種情況。在 Windows 7、Windows Server 2008 R2 及更新版本上，如果在使用 802.1X 以外的方法進行驗證的配置檔上呼叫 WlanSetProfileEapXmlUserData 函式，就會傳回此值。
ERROR_SERVICE_NOT_ACTIVE	尚未啟動服務。如果無線 LAN 服務未執行，則會傳回此值。
RPC_STATUS	各種錯誤碼。

備註

WlanSetProfileEapXmlUserData 函式會設定要在配置檔上使用的 EAP 用戶認證。此函式只能在使用 802.1X 進行驗證的配置檔上呼叫。在 Windows Vista 和 Windows Server 2008 上，這些認證只能由呼叫端使用。

eapType 參數是EAP_METHOD_TYPE結構，其中包含 EAP 方法的類型、識別和作者資訊。 EAP_METHOD_TYPE 結構的 eapType 成員是EAP_TYPE結構，其中包含 EAP 方法的類型和廠商識別資訊。

如需 EAP 方法類型配置的詳細資訊，請參閱 IETF 所發佈的 RFC 3748 第 6.2 節。

在 Windows 10、Windows Server 2016 及更新版本上，會增強 WlanSetProfileEapXmlUserData 函式。如果 dwFlags 參數包含 WLAN_SET_EAPHOST_DATA_ALL_USERS，則可以為配置檔的所有使用者設定 EAP 用戶認證。

執行設定文件作業時，所有無線 LAN 函式都需要無線介面的介面 GUID。拿掉無線介面時，其狀態會從無線 LAN 服務 (WLANSVC) 清除，而且無法執行任何配置檔作業。

如果 pInterfaceGuid 參數中指定的無線介面已從系統中移除，則 WlanSetProfileEapXmlUserData 函式可能會失敗 ERROR_INVALID_PARAMETER， (已移除的 USB 無線適配卡，例如) 。

當您使用 EAP-TTLS 時， WlanSetProfileEapXmlUserData 可能會在您使用 EAP-TTLS 時造成無線連線失敗，而 API 是從 64 位操作系統上執行的 32 位應用程式呼叫， (OS) 。您的應用程式應該針對與目標OS相同的CPU架構來建置。

Windows XP 搭配 SP3 和適用於 Windows XP 的無線 LAN API 與 SP2： 此函式只能用於受保護的 EAP (PEAP) 認證。它無法用於其他 EAP 類型。

規格需求

需求	值
最低支援的用戶端	Windows Vista、Windows XP 與 SP3 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	wlanapi.h (包含 Wlanapi.h)
程式庫	Wlanapi.lib
Dll	Wlanapi.dll
可轉散發套件	適用於 Windows XP 與 SP2 的無線 LAN API