Connectivity Diagnostics API

تسمح واجهة 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.