WlanHostedNetworkQuerySecondaryKey 函式 (wlanapi.h)

發行項
03/15/2023

WlanHostedNetworkQuerySecondaryKey 函式會查詢已設定為由無線託管網路使用的次要安全性金鑰。

語法

DWORD WlanHostedNetworkQuerySecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [out]           PDWORD                      pdwKeyLength,
  [out]           PUCHAR                      *ppucKeyData,
  [out]           PBOOL                       pbIsPassPhrase,
  [out]           PBOOL                       pbPersistent,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  PVOID                       pvReserved
);

參數

[in] hClientHandle

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

[out] pdwKeyLength

值的指標，指定 ppucKeyData 參數所指向之索引鍵資料陣列中有效資料位元組數目，如果 WlanHostedNetworkQuerySecondaryKey 函式的呼叫成功。

如果金鑰是複雜密碼，此金鑰長度會包含終止 '\0'。

[out] ppucKeyData

如果 WlanHostedNetworkQuerySecondaryKey 函式的呼叫成功，則為值指標，接收以次要安全性金鑰資料傳回之緩衝區的指標。

[out] pbIsPassPhrase

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

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

[out] pbPersistent

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

如果此參數為 TRUE，則稍後會儲存及重複使用索引鍵資料陣列。如果此參數為 FALSE，則索引鍵資料陣列僅供一次性使用。

[out, optional] pFailReason

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

pvReserved

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

傳回值

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

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

傳回碼	描述
ERROR_INVALID_HANDLE	控制碼無效。如果在控制碼資料表中找不到 hClientHandle 參數中指定的控制碼，就會傳回此錯誤。
ERROR_INVALID_PARAMETER	參數不正確。如果發生下列任一情況，就會傳回此錯誤： hClientHandle 為 Null。 pdwKeyLength 為 Null。 ppucKeyData 為 Null 或無效。 pbIsPassPhrase 為 Null 或無效。 pbPersistent 為 Null。 pvReserved 不是 Null。
ERROR_INVALID_STATE	資源未處於執行要求作業的正確狀態。如果無線託管網路正在進行關機，就會發生這種情況。
ERROR_OUTOFMEMORY	儲存體不足，無法完成此作業。
ERROR_SERVICE_NOT_ACTIVE	尚未啟動服務。如果 WLAN 自動設定服務未執行，就會傳回此錯誤。
其他	各種 RPC 和其他錯誤碼。使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

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

用戶端應用程式會呼叫 WlanHostedNetworkQuerySecondaryKey 函式，以查詢無線託管網路將使用的次要安全性金鑰。此函式會傳回金鑰資訊，包括金鑰資料、金鑰長度、是否為複雜密碼，以及它是持續性還是一次性使用。此函式不會變更無線託管網路的狀態或屬性。

如果 pbIsPassPhrase 參數所指向的值是 TRUE，則次要安全性金鑰是複雜密碼。如果 pbIsPassPhrase 參數所指向的值是 FALSE，則次要安全性金鑰是二進位金鑰。

ppucKeyData參數所指向之緩衝區中傳回的次要安全性金鑰會與 WPA2-Personal 驗證搭配使用，且格式如下：

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

如果 pbPersistent 參數所指向的值為 TRUE，則次要安全性金鑰是持續性的。永續性時，如果主機網路已經啟動，也會在未來啟動時重複使用次要安全性金鑰。

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

如果目前沒有設定次要安全性金鑰， pdwKeyLength 參數所指向的傳回值將會是零，而 ppucKeyData 參數中傳回的值會是 Null。在這種情況下， pbIsPassPhrase 和 pbPersistent 參數中傳回的值將無意義。

如果WlanHostedNetworkQuerySecondaryKey函式成功，則呼叫WlanFreeMemory函式之後，應該釋放用於ppucKeyData參數中緩衝區的記憶體。

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

在 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