واجهة برمجة تطبيقات بيانات تشخيص إمكانية الاتصال

تسمح واجهة برمجة التطبيقات Connectivity Diagnostics API للتطبيقات التي تملك الشبكات أو تديرها، مثل تطبيقات مشغّل شبكة الجوّال وتطبيقات شبكة VPN وتطبيقات اقتراحات Wi-Fi، بتلقّي معلومات تشخيصية عن اتصال الشبكة من إطار العمل. ويمكن لهذه التطبيقات تسجيل عمليات معاودة الاتصال وتلقّي إشعارات تتضمّن معلومات عن إمكانية الاتصال بالشبكات التي تملكها أو تديرها. لن تتلقّى التطبيقات إشعارات بشأن الشبكات التي لا يملكها التطبيق أو يديرها.

في ما يلي أمثلة على التطبيقات التي تدير الشبكات أو تملكها:

  • تطبيقات مشغّلي شبكات الجوّال: إدارة الشبكات الجوّالة التي تملك subId امتيازات مشغّل شبكة الجوّال لها
  • تطبيقات اقتراح شبكات Wi-Fi: تملك شبكات Wi-Fi تقترحها على النظام
  • تطبيقات شبكة VPN: تدير جميع الشبكات التي تستخدمها شبكة VPN، ولكن فقط عندما تكون هي شبكة VPN النشطة

يتم استدعاء عمليات معاودة الاتصال في الحالات التالية:

  • التحقُّق من الشبكة: انتهى النظام من تقييم شبكة معيَّنة. تقدّم فئة ConnectivityReport معلومات عن الحالة الحالية للشبكة و نتائج أي اختبارات أو إجراءات تم إجراؤها كجزء من عملية التحقّق.

    public class ConnectivityReport {
    Network network;
    long reportTimestamp;
    LinkProperties linkProperties;
    NetworkCapabilities networkCapabilities;
    PersistableBundle additionalInfo;
}

  • وجود عطل بيانات مشتبه به: يُشتبه في احتمال تعطُّل البيانات، وهو حالة لا تتدفق فيها حِزم IP بشكل صحيح عبر الشبكة. تقدّم فئة DataStallReport معلومات عن حالات توقّف البيانات المُشتبه بها.

    public class DataStallReport {
    Network network;
    long reportTimestamp;
    int detectionMethod;
    LinkProperties linkProperties;
    NetworkCapabilities networkCapabilities;
    PersistableBundle stallDetails;
}

  • تم الإبلاغ عن الاتصال: أبلغ أحد التطبيقات عن الاتصال بالنظام من خلال ConnectivityManager#reportNetworkConnectivity. تتم مشاركة معلومات الشبكة وحالة الاتصال (سواء كان التطبيق يعتقد أنّ الشبكة تتيح الاتصال أو لا).

التنفيذ

لاستخدام Connectivity Diagnostics API، يجب أن يحصل التطبيق على مثيل ConnectivityDiagnosticsManager من المنصة. يجب استخدام هذه النسخة لتسجيل عمليات تنفيذ ConnectivityDiagnosticsCallback وإلغاء تسجيلها. إنّ طرق ردّ المكالمات التي لا يتم إلغاؤها لا تؤدي إلى أيّ إجراء.

في ما يلي مثال على تنفيذ ConnectivityDiagnosticsCallback:

public class ExampleCallback extends ConnectivityDiagnosticsCallback {
    @Override
    public void onConnectivityReportAvailable(@NonNull ConnectivityReport report) {
        ... 
        // Log data, take action based on report result, etc
        ... 
    }

    @Override
    public void onDataStallSuspected(@NonNull DataStallReport report) {
        ... 
        // Log data, take action based on report result, etc
        ... 
    }

    @Override
    public void onNetworkConnectivityReported(
               @NonNull Network network, boolean hasConnectivity) {
        ... 
        // Log data, take action based on report result, etc
        ... 
    }
}

لتسجيل عمليات معاودة الاتصال وتلقّي الإشعارات، يمكنك الاتصال بالرقم registerConnectivityDiagnosticsCallback. لإلغاء تسجيل عمليات تسجيل المكالمات وإيقاف تلقّي الإشعارات، اتصل بالرقم unregisterConnectivityDiagnosticsCallback.

في ما يلي مثال على التسجيل والإلغاء ConnectivityDiagnosticsCallback:

NetworkRequest request =
        new NetworkRequest.Builder()
                .addTransportType(TRANSPORT_CELLULAR)
                .build();
// Use an Executor that is appropriate for your use case
Executor executor = Executors.newSingleThreadExecutor();

ConnectivityDiagnosticsManager cdm =
        context.getSystemService(ConnectivityDiagnosticsManager.class);

ExampleCallback callback = new ExampleCallback();
cdm.registerConnectivityDiagnosticsCallback(
        request, executor, callback);

... 
// Collect connectivity information on networks that match with request
... 

cdm.unregisterConnectivityDiagnosticsCallback(callback);

التحقُّق

تم اختبار واجهة Connectivity Diagnostics API من خلال مجموعة أدوات اختبار التوافق (CTS) من قِبل ConnectivityDiagnosticsManagerTest.