Connectivity Diagnostics API

‫Connectivity Diagnostics API מאפשר לאפליקציות שהן הבעלים של רשתות או מנהלות רשתות, כמו אפליקציות של ספקי סלולר, אפליקציות VPN ואפליקציות להצעות לחיבור Wi-Fi, לקבל מהמסגרת מידע אבחוני על קישוריות לרשת. האפליקציות האלה יכולות לרשום קריאות חוזרות (callbacks) ולקבל התראות עם פרטי קישוריות לרשתות שבבעלותן או בניהולן. אפליקציות לא יקבלו התראות לגבי רשתות שלא נמצאות בבעלות האפליקציה או בניהולה.

דוגמאות לאפליקציות שמנהלות רשתות או שהן הבעלים של רשתות:

• אפליקציות של ספקי סלולר: ניהול רשתות סלולריות שבהן ל-subId יש הרשאות של ספק סלולר
• אפליקציות להצעות לרשתות Wi-Fi: רשתות Wi-Fi בבעלות האפליקציות שהן מציעות למערכת
• אפליקציות VPN: ניהול כל הרשתות שבהן נעשה שימוש ב-VPN, אבל רק כשהן ה-VPN הפעיל

הקריאות החוזרות (callbacks) מופעלות במקרים הבאים:

• אימות הרשת: המערכת סיימה להעריך רשת ספציפית. המחלקות 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 למערכת. המידע שמשותף כולל את הרשת ואת הקישוריות שדווחה (אם האפליקציה חושבת שהרשת מספקת קישוריות או לא).

הטמעה

כדי להשתמש ב-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);

אימות

ממשק ה-API של אבחון הקישוריות נבדק על ידי CTS על ידי ConnectivityDiagnosticsManagerTest.