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

• يُحتمل حدوث توقّف مؤقت للبيانات: يُحتمل حدوث توقّف مؤقت للبيانات، وهو حالة لا تتدفّق فيها حِزم بروتوكول الإنترنت بشكل سليم عبر الشبكة. تقدّم الفئة 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.