儲存網路和 Passpoint 設定

在 Android 11 (SDK 級別 30) 以上版本中，應用程式可以使用 android.provider.Settings.ACTION_WIFI_ADD_NETWORKS 意圖引導使用者新增一或多個已儲存的網路或 Passpoint 設定。API 也能原封不動運作，用來修改現有的已儲存設定。

注意： 這個 API 是功能最接近已淘汰 WifiManager.addNetwork(WifiConfiguration config) API 的功能，可將產生的設定新增至面向使用者且代管的已儲存網路和訂閱清單。

如要儲存網路或 Passpoint 設定，請按照下列步驟操作：

1. 建立 ACTION_WIFI_ADD_NETWORKS 意圖。

2. 使用 WifiNetworkSuggestion.Builder 建立一或多項設定。請注意，即使您使用 WifiNetworkSuggestion，這個 Intent API 與 建議 API 無關。

3. 建立設定的可包裝陣列清單，並使用 EXTRA_WIFI_NETWORK_LIST 額外項目將其附加至意圖。

4. 執行 Activity.startActivityForResult() 並傳入意圖。

5. 請使用 Activity.onActivityResult() 回呼監聽結果。

   resultCode 可以是下列其中一項：

   • Activity.RESULT_OK：表示使用者已接受並儲存提議的網路。
   • Activity.RESULT_CANCELED：表示使用者已拒絕提議的網路。

   如果 resultCode 是 RESULT_OK，則 Intent 資料會包含 EXTRA_WIFI_NETWORK_RESULT_LIST 額外項目，其中包含的結果代碼陣列，指出個別設定是否已成功儲存。可能的結果代碼如下：

   • ADD_WIFI_RESULT_SUCCESS：已新增或成功更新設定。
   • ADD_WIFI_RESULT_ADD_OR_UPDATE_FAILED：嘗試新增設定時會失敗，例如設定格式錯誤。
   • ADD_WIFI_RESULT_ALREADY_EXISTS：要求的設定已存在，因此無須採取任何行動。

6. 如果要求成功，平台會觸發連至其中一個新儲存網路的連線。

程式碼範例

以下程式碼範例顯示如何儲存網路或 Passpoint 設定。

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
    }

    fun startOperation() {
        val suggestions = ArrayList<WifiNetworkSuggestion>()

        // WPA2 configuration
        suggestions.add(
                WifiNetworkSuggestion.Builder()
                        .setSsid("test111111")
                        .setWpa2Passphrase("test123456")
                        .build()
        )

        // Open configuration
        suggestions.add(
                WifiNetworkSuggestion.Builder()
                        .setSsid("test222222")
                        .build()
        )

        // Passpoint configuration
        val config = PasspointConfiguration()
        config.credential = Credential().apply {
            realm = "realm.example.com"
            simCredential = Credential.SimCredential().apply {
                eapType = 18
                imsi = "123456*"
            }
        }
        config.homeSp = HomeSp().apply {
            fqdn = "test1.example.com"
            friendlyName = "Some Friendly Name"
        }
        suggestions.add(
                WifiNetworkSuggestion.Builder()
                        .setPasspointConfig(config)
                        .build())

        // Create intent
        val bundle = Bundle()
        bundle.putParcelableArrayList(EXTRA_WIFI_NETWORK_LIST, suggestions)
        val intent = Intent(ACTION_WIFI_ADD_NETWORKS)
        intent.putExtras(bundle)

        // Launch intent
        startActivityForResult(intent, 0)
    }

    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
        if(resultCode == RESULT_OK) {
            // user agreed to save configurations: still need to check individual results
            if (data != null && data.hasExtra(EXTRA_WIFI_NETWORK_RESULT_LIST)) {
                for (code in data.getIntegerArrayListExtra(EXTRA_WIFI_NETWORK_RESULT_LIST)) {
                    when (code) {
                        ADD_WIFI_RESULT_SUCCESS ->
                            ... // Configuration saved or modified
                        ADD_WIFI_RESULT_ADD_OR_UPDATE_FAILED ->
                            ... // Something went wrong - invalid configuration
                        ADD_WIFI_RESULT_ALREADY_EXISTS ->
                            ... // Configuration existed (as-is) on device, nothing changed
                        else ->
                            ... // Other errors
                    }
                }
            }
        } else {
            // User refused to save configurations
        }
    }
}