共用方式為


WlanHostedNetworkSetSecondaryKey 函式 (wlanapi.h)

WlanHostedNetworkSetSecondaryKey 函式會設定無線託管網路將使用的次要安全性金鑰。

語法

DWORD WlanHostedNetworkSetSecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [in]            DWORD                       dwKeyLength,
  [in]            PUCHAR                      pucKeyData,
  [in]            BOOL                        bIsPassPhrase,
  [in]            BOOL                        bPersistent,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  PVOID                       pvReserved
);

參數

[in] hClientHandle

用戶端的會話控制碼,由先前呼叫 WlanOpenHandle 函式所傳回。

[in] dwKeyLength

pucKeyData參數所指向之索引鍵資料陣列中的有效資料位元組數目。 如果金鑰是複雜密碼,此金鑰長度應該包含終止 '\0'。

[in] pucKeyData

包含索引鍵資料的緩衝區指標。 緩衝區中有效資料位元組的數目至少必須是 dwKeyLength 參數中指定的值。

[in] bIsPassPhrase

布林值,指出 pucKeyData 參數所指向的索引鍵資料陣列是否為複雜密碼格式。

如果此參數為 TRUE,索引鍵資料陣列會是複雜密碼格式。 如果此參數為 FALSE,則索引鍵資料陣列不是複雜密碼格式。

[in] bPersistent

布林值,指出 pucKeyData 參數所指向的索引鍵資料陣列是否要儲存並稍後重複使用,或僅供一次性使用。

如果此參數為 TRUE,則稍後會儲存並重複使用索引鍵資料陣列。 如果此參數為 FALSE,則索引鍵資料陣列會用於一個會話, (目前會話,如果未啟動裝載網路,則為下一個會話) 。

[out, optional] pFailReason

如果 WlanHostedNetworkSetSecondaryKey 函式的呼叫失敗,則為接收失敗原因之值的選擇性指標。 失敗原因的可能值來自Wlanapi.h標頭檔中定義的WLAN_HOSTED_NETWORK_REASON列舉類型。

pvReserved

保留供未來使用。 此參數必須是 Null

傳回值

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

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

傳回碼 描述
ERROR_INVALID_HANDLE
控制碼無效。 如果在控制碼資料表中找不到 hClientHandle 參數中指定的控制碼,就會傳回此錯誤。
ERROR_INVALID_PARAMETER
參數不正確。 如果發生下列任一狀況,就會傳回此錯誤:
  • hClientHandleNull
  • pucKeyDataNull
  • pucKeyData 不會指向格式正確的有效金鑰。
  • pvReserved 不是 Null
ERROR_INVALID_STATE
資源未處於執行要求作業的正確狀態。 如果無線託管網路正在進行關機,就會發生這種情況。
ERROR_SERVICE_NOT_ACTIVE
尚未啟動服務。 如果 WLAN 自動設定服務未執行,則會傳回此錯誤。
其他
各種 RPC 和其他錯誤碼。 使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

WlanHostedNetworkSetSecondaryKey 函式是新增的原生無線 API 擴充功能,可支援 Windows 7 和 Windows Server 2008 R2 上安裝無線區域網路 服務的無線託管網路。

用戶端應用程式會呼叫 WlanHostedNetworkSetSecondaryKey 函式,以設定無線託管網路將使用的次要安全性金鑰。 如果呼叫應用程式使用hClientHandle參數呼叫 WlanCloseHandle () 或進程結束,呼叫WlanCloseHandle,則不會自動復原此函式所造成的任何裝載網路變更。

一旦啟動,無線裝載網路除了主要安全性金鑰之外,也允許無線對等與這個次要安全性金鑰產生關聯。 次要安全性金鑰一律會視需要由使用者指定,而主要安全性金鑰是由具有更高安全性強度的作業系統所產生。

pucKeyData參數所指向緩衝區中傳遞的次要安全性金鑰會與 WPA2-Personal 驗證搭配使用,且格式應為下列其中一種:

  • 由 8 到 63 個字元的 ASCII 字元陣列所組成的金鑰複雜密碼。 dwKeyLength參數應該在複雜密碼中包含終止 '\0'。 dwKeyLength參數的值應該介於 9 到 64 的範圍內。
  • 二進位索引鍵,包含 32 個位元組的二進位索引鍵資料。 二進位索引 鍵的 dwKeyLength 參數應該是 32。

若要設定有效的次要安全性金鑰, dwKeyLength 參數應該位於正確的範圍內, 而 pucKeyData 參數應該指向包含指定之資料位元組的有效記憶體緩衝區。 若要從系統移除目前設定的次要安全性金鑰,應用程式應該使用dwKeyLength參數中的零和pucKeyData參數中的Null呼叫WlanHostedNetworkSetSecondaryKey函式。

如果pucKeyData參數是Null,但dwKeyLength參數不是零,WlanHostedNetworkSetSecondaryKey函式會傳回ERROR_INVALID_PARAMETER。 如果dwKeyLength參數為零,但pucKeyData參數不是NullWlanHostedNetworkSetSecondaryKey 函式也會傳回ERROR_INVALID_PARAMETER

次要安全性金鑰通常會在無線託管網路啟動之前設定。 然後,下次啟動託管網路時,將會使用它。

在啟動託管網路之後,也可以設定次要安全性金鑰。 在此情況下,將會立即使用次要安全性金鑰。 任何使用先前次要安全性金鑰的用戶端都會保持連線,但如果因任何原因而中斷連線,或無線託管網路重新開機,將無法重新連線。

如果 bPersistent 參數設定為 TRUE,則可以將次要安全性金鑰指定為持續性。 當指定為持續性時,如果主機網路已啟動,則會立即使用次要安全性金鑰,並在未來每當啟動託管網路時重複使用。

如果未將次要安全性金鑰指定為永續性,則會在主機網路已啟動時立即使用,或只在下一次啟動託管網路時使用。 在主機網路停止之後,此次要安全性金鑰永遠不會再次使用,而且會從系統中移除。

任何使用者可以呼叫此函式,以設定要用於託管網路的次要安全性金鑰。 不過,啟用無線託管網路的能力可能會受限於網域中的群組原則。

在 Windows 7 和更新版本上,如果電腦上存在支援託管網路的無線介面卡,作業系統就會安裝虛擬裝置。 如果電腦具有單一無線網路介面卡,此虛擬裝置通常會顯示在「網路連線資料夾」中顯示為「無線網路連線 2」,且裝置名稱為 「Microsoft Virtual WiFi Miniport 配接器」。 此虛擬裝置專門用來執行軟體存取點 (SoftAP) 連線,而且不會出現在 WlanEnumInterfaces 函式所傳回的清單中。 此虛擬裝置的存留期會系結至實體無線介面卡。 如果實體無線介面卡已停用,也會移除此虛擬裝置。 此功能也適用于已安裝無線區域網路 服務的 Windows Server 2008 R2。

規格需求

   
最低支援的用戶端 Windows 7 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 R2 [僅限桌面應用程式]
目標平台 Windows
標頭 wlanapi.h (包含 Wlanapi.h)
程式庫 Wlanapi.lib
Dll Wlanapi.dll

另請參閱

關於無線託管網路

使用無線裝載的網路和網際網路連線共用

WLAN_HOSTED_NETWORK_REASON

WlanCloseHandle

WlanEnumInterfaces

WlanHostedNetworkInitSettings

WlanHostedNetworkQueryProperty

WlanHostedNetworkQuerySecondaryKey

WlanHostedNetworkRefreshSecuritySettings

WlanHostedNetworkSetProperty

WlanOpenHandle