共用方式為

WlanSetProfile 函式 (wlanapi.h)

  • 發行項

WlanSetProfile 函式會設定特定配置文件的內容。

語法

DWORD WlanSetProfile(
  [in]           HANDLE     hClientHandle,
  [in]           const GUID *pInterfaceGuid,
  [in]           DWORD      dwFlags,
  [in]           LPCWSTR    strProfileXml,
  [in, optional] LPCWSTR    strAllUserProfileSecurity,
  [in]           BOOL       bOverwrite,
  [in]           PVOID      pReserved,
  [out]          DWORD      *pdwReasonCode
);

參數

[in] hClientHandle

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

[in] pInterfaceGuid

介面的 GUID。

[in] dwFlags

要設定在配置檔上的旗標。

Windows XP 搭配 SP3 和適用於 Windows XP 的無線 LAN API 與 SP2： dwFlags 必須為 0。 不支援個別使用者配置檔。

值 意義
0
 配置檔是所有使用者配置檔。
WLAN_PROFILE_GROUP_POLICY
0x00000001
 配置檔是組策略配置檔。
WLAN_PROFILE_USER
0x00000002
 配置檔是個別使用者配置檔。

[in] strProfileXml

包含設定檔的 XML 表示法。 WLANProfile 元素是根配置檔元素。 若要檢視範例配置檔，請參閱 無線配置檔範例。 沒有預先定義的字串長度上限。

Windows XP 搭配 SP3 和適用於 Windows XP 的無線 LAN API 與 SP2： 提供的配置文件必須符合 無線配置檔相容性中所述的相容性準則。

[in, optional] strAllUserProfileSecurity

在所有使用者配置檔上設定安全性描述元字串。 如需配置檔許可權的詳細資訊，請參閱一節。

如果 dwFlags 設定為 WLAN_PROFILE_USER，則會忽略此參數。

如果此參數已針對新的所有使用者配置檔設定為 NULL ，則會使用與 wlan_secure_add_new_all_user_profiles 對象相關聯的安全性描述元。 如果 WlanSetSecuritySettings 呼叫尚未修改安全性描述元，則所有使用者都有新所有使用者配置檔的默認許可權。 呼叫 WlanGetSecuritySettings 以取得與wlan_secure_add_new_all_user_profiles對象相關聯的默認許可權。

如果此參數設定為現有所有使用者配置檔的 NULL ，則配置檔的許可權不會變更。

如果所有使用者配置檔的此參數不是 NULL ，則會在建立安全性描述元物件並剖析為字串之後，建立或修改與配置檔相關聯的安全性描述元字串。

Windows XP 搭配 SP3 和適用於 Windows XP 的無線 LAN API 與 SP2： 此參數必須是 NULL。

[in] bOverwrite

指定此設定檔是否覆寫現有的設定檔。 如果此參數為 FALSE 且設定檔已經存在，則不會覆寫現有的配置檔，並傳回錯誤。

[in] pReserved

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

[out] pdwReasonCode

指出配置檔無效原因 的WLAN_REASON_CODE 值。

傳回值

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

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

傳回碼 Description
ERROR_ACCESS_DENIED
 呼叫端沒有足夠的許可權可設定配置檔。

使用 dwFlags 呼叫時設定為 0 ，也就是設定所有使用者配置檔時 - WlanSetProfile 會擷取 (DACL) 與 wlan_secure_add_new_all_user_profiles 物件一起儲存的任意存取控制清單。 以 dwFlags 設定為 WLAN_PROFILE_USER 呼叫時，也就是設定個別使用者配置檔時 - WlanSetProfile 會擷取與 wlan_secure_add_new_per_user_profiles 物件一起儲存 (DA) CL 的任意存取控制清單。 在任一情況下，如果 DACL 不包含存取控制專案 (ACE) 授與呼叫線程之存取令牌的WLAN_WRITE_ACCESS許可權， 則 WlanSetProfile 會傳回 ERROR_ACCESS_DENIED。
ERROR_ALREADY_EXISTS
 strProfileXml 指定已經存在的網路。 一般而言，當 bOverwrite 為 FALSE 時，會使用此傳回值;不過，如果 bOverwrite 為 TRUE 且 dwFlags 指定與現有配置檔所使用的配置檔類型不同，則不會覆寫現有的配置檔，而且會傳回 ERROR_ALREADY_EXISTS 。
ERROR_BAD_PROFILE
 strProfileXml 指定的配置檔無效。 如果傳回此值， pdwReasonCode 會指定配置檔無效的原因。
ERROR_INVALID_PARAMETER
 發生下列其中一個條件：
  • hClientHandle 為 NULL 或無效。
  • pInterfaceGuid 為 NULL。
  • pReserved 不是 NULL。
  • strProfileXml 為 NULL。
    • [ConfigBlob] (/windows/desktop/eaphost/eaphostconfigschema-configblob-eaphostconfig-element) 。 如果設定檔必須有空 的 ConfigBlob，請在 <ConfigBlob>00</ConfigBlob> 設定檔中使用 。
  • pdwReasonCode 為 NULL。
  • dwFlags 未設定為其中一個指定的值。
  • dwFlags 設定為 WLAN_PROFILE_GROUP_POLICY， 而 bOverwrite 設定為 FALSE。
ERROR_NO_MATCH
 介面不支援配置檔中指定的一或多個功能。 例如，如果配置檔指定當 NIC 只支援 WPA 時使用 WPA2，則會傳回此錯誤碼。 此外，如果配置檔指定當 NIC 不支援 FIPS 模式時使用 FIPS 模式，則會傳回此錯誤碼。
RPC_STATUS
 各種錯誤碼。

備註

WlanSetProfile 函式可用來新增無線 LAN 配置檔，或取代現有的無線 LAN 配置檔。

在組策略配置檔之後，清單頂端會新增新的配置檔。 如果覆寫現有的配置檔，則清單中的位置不會變更。Windows XP 搭配 SP3 和適用於 Windows XP 的無線 LAN API 與 SP2：

臨機操作配置檔會出現在配置檔清單中的基礎結構配置文件之後。 如果您建立新的臨機操作配置檔，則會放在組策略和基礎結構配置檔之後的臨機操作清單頂端。

不支援 802.1X 客體配置檔、無線布建服務 (WPS) 配置檔，以及 Wi-Fi 具有受保護 Access-None (WPA-None) 驗證的配置檔。 這表示無法使用原生 Wifi 函式來建立、刪除、列舉或存取這類配置檔。 任何已在慣用配置檔清單中的任何這類配置檔都會保留在清單中，而且其相對於其他配置檔的位置是固定的，除非其他配置檔的位置變更。

您可以在配置檔上呼叫 WlanSetProfile ，其中包含純文本密鑰 (，也就是具有 受保護 元素的配置檔，並將 設定為 FALSE) 。 配置檔案儲存在設定檔存放區之前，金鑰數據會自動加密。 當後續呼叫 WlanGetProfile 從配置檔存放區擷取配置檔時，會傳回加密密鑰數據。Windows XP 搭配 SP3 和適用於 Windows XP 的無線 LAN API 與 SP2： 金鑰資料永遠不會加密。

所有使用者配置檔都有三個相關聯的許可權：讀取、寫入和執行。 如果使用者具有讀取許可權，用戶可以檢視配置檔許可權。 如果使用者具有執行存取權，則使用者具有讀取許可權，而且使用者也可以使用配置檔連線到網路並中斷連線。 如果使用者具有寫入許可權，則使用者具有執行存取權，而且使用者也可以修改和刪除與配置文件相關聯的許可權。

下列說明建立安全性描述元物件的程式，並將它剖析為字串。

  1. 呼叫 InitializeSecurityDescriptor 以在記憶體中建立安全性描述元。
  2. 呼叫 SetSecurityDescriptorOwner。
  3. 呼叫 InitializeAcl 以在記憶體中建立 DACL) (任意存取控制清單。
  4. 呼叫 AddAccessAllowedAce 或 AddAccessDeniedAce ，將訪問控制專案新增至 DACL (ACE) 。 視需要將 AccessMask 參數設定為下列其中一項：
    • WLAN_READ_ACCESS
    • WLAN_EXECUTE_ACCESS
    • WLAN_WRITE_ACCESS
  5. 呼叫 SetSecurityDescriptorDacl ，將 DACL 新增至安全性描述元。
  6. 呼叫 ConvertSecurityDescriptorToStringSecurityDescriptor ，將描述元轉換為字串。
當呼叫 WlanSetProfile 時，ConvertSecurityDescriptorToStringSecurityDescriptor 所傳回的字串可以當做 strAllUserProfileSecurity 參數值使用。

針對 Native Wifi AutoConfig 服務所使用的每個無線 LAN 配置檔，Windows 會維護自定義用戶數據的概念。 此自定義用戶數據一開始不存在，但可以藉由呼叫 WlanSetProfileCustomUserData 函式來設定。 每當呼叫 WlanSetProfile 函式來修改配置檔時，自定義用戶數據就會重設為空白。 設定自定義用戶數據之後，可以使用 WlanGetProfileCustomUserData 函式來存取此數據。

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

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

netsh wlan add profile 命令會在命令行提供類似的功能。 如需詳細資訊，請參閱 無線區域網路的 Netsh 命令 (wlan) 。

規格需求

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

另請參閱

ConvertSecurityDescriptorToStringSecurityDescriptor

InitializeAcl

InitializeSecurityDescriptor

原生 Wifi API 許可權

SetSecurityDescriptorDacl

WlanGetProfile

WlanGetProfileCustomUserData

WlanGetProfileList

WlanQueryInterface

WlanSetProfileCustomUserData

WlanSetProfileEapUserData

WlanSetProfileEapXmlUserData