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

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

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

1. إنشاء هدف ACTION_WIFI_ADD_NETWORKS

2. أنشِئ إعدادًا واحدًا أو أكثر باستخدام WifiNetworkSuggestion.Builder. يُرجى العِلم أنّه على الرغم من استخدام WifiNetworkSuggestion، فإنّ واجهة برمجة تطبيقات Intent هذه غير مرتبطة بواجهة برمجة التطبيقات Recommendationion 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. وإذا نجح الطلب، يشغّل النظام الأساسي اتصالاً بإحدى الشبكات المحفوظة حديثًا.

نموذج التعليمات البرمجية

يوضّح نموذج الرمز التالي كيفية حفظ إعدادات الشبكة أو نقطة المرور.

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