حفظ الشبكات وإعدادات Passpoint

في الإصدار 11 من نظام التشغيل Android (المستوى 30 من حزمة تطوير البرامج (SDK)) والإصدارات الأحدث، يمكن للتطبيقات استخدام android.provider.Settings.ACTION_WIFI_ADD_NETWORKS Intent لتوجيه المستخدم خلال عملية إضافة شبكة محفوظة جديدة واحدة أو أكثر أو إعدادات Passpoint. تعمل واجهة برمجة التطبيقات أيضًا على تعديل الإعدادات الحالية المحفوظة.

لحفظ إعدادات شبكة أو إعدادات Passpoint، اتّبِع الخطوات التالية:

1. أنشئ نية ACTION_WIFI_ADD_NETWORKS.

2. أنشئ إعدادًا واحدًا أو أكثر باستخدام WifiNetworkSuggestion.Builder. يُرجى العلم أنّه على الرغم من استخدام WifiNetworkSuggestion، فإنّ واجهة برمجة التطبيقات Intent API هذه لا تكون مرتبطة بواجهة برمجة التطبيقات Suggestion API.

3. أنشئ قائمة مصفوفة قابلة للتقسيم من الإعدادات واربطها بالهدف باستخدام العنصر الإضافي EXTRA_WIFI_NETWORK_LIST.

4. نفِّذ Activity.startActivityForResult()، مع تضمين النية.

5. استمع إلى النتيجة باستخدام الدالة callback Activity.onActivityResult().

   يمكن أن يكون resultCode أيًّا مما يلي:

   • ‫Activity.RESULT_OK: يشير ذلك إلى أنّ المستخدم وافق على الشبكات المقترَحة وحفظها.
   • ‫Activity.RESULT_CANCELED: يشير ذلك إلى أنّ المستخدم رفض الشبكات المقترَحة.

   إذا كان resultCode هو RESULT_OK، تحتوي البيانات Intent على العنصر EXTRA_WIFI_NETWORK_RESULT_LIST extra الذي يحتوي على صفيف من رموز النتائج التي تشير إلى ما إذا تم حفظ الإعدادات الفردية بنجاح. في ما يلي رموز النتائج المحتمَلة:

   • 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
        }
    }
}