API Chẩn đoán kết nối

API Chẩn đoán khả năng kết nối cho phép các ứng dụng sở hữu hoặc quản lý mạng (chẳng hạn như ứng dụng của nhà mạng, ứng dụng VPN và ứng dụng đề xuất Wi-Fi) nhận thông tin chẩn đoán về khả năng kết nối mạng từ khung. Các ứng dụng này có thể đăng ký lệnh gọi lại và nhận thông báo có thông tin về khả năng kết nối cho các mạng mà chúng sở hữu hoặc quản lý. Các ứng dụng sẽ không nhận được thông báo cho những mạng không do ứng dụng sở hữu hoặc quản lý.

Sau đây là ví dụ về các ứng dụng quản lý hoặc sở hữu mạng:

  • Ứng dụng của nhà mạng: Quản lý mạng di động mà subId của ứng dụng có đặc quyền của nhà mạng
  • Ứng dụng đề xuất Wi-Fi: Sở hữu các mạng Wi-Fi mà ứng dụng đề xuất cho hệ thống
  • Ứng dụng VPN: Quản lý tất cả các mạng mà VPN của ứng dụng sử dụng, nhưng chỉ khi ứng dụng đó là VPN đang hoạt động

Lệnh gọi lại được gọi trong các trường hợp sau:

  • Xác thực mạng: Hệ thống đã hoàn tất việc đánh giá một mạng cụ thể. Lớp ConnectivityReport cung cấp thông tin về trạng thái hiện tại của mạng và kết quả của mọi bài kiểm tra hoặc quy trình được thực hiện trong quá trình xác thực.

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

  • Nghi ngờ bị tắc nghẽn dữ liệu: Nghi ngờ bị tắc nghẽn dữ liệu (tình trạng các gói IP không truyền đúng cách qua mạng). Lớp DataStallReport cung cấp thông tin về các trường hợp nghi ngờ bị tắc nghẽn dữ liệu.

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

  • Đã báo cáo khả năng kết nối: Một ứng dụng đã báo cáo khả năng kết nối thông qua ConnectivityManager#reportNetworkConnectivity cho hệ thống. Mạng và khả năng kết nối được báo cáo (cho dù ứng dụng tin rằng mạng có hoặc không cung cấp khả năng kết nối) sẽ được chia sẻ.

Triển khai

Để sử dụng API Chẩn đoán khả năng kết nối, ứng dụng phải lấy ConnectivityDiagnosticsManager thực thể từ nền tảng. Bạn nên sử dụng thực thể này để đăng ký và huỷ đăng ký ConnectivityDiagnosticsCallback các hoạt động triển khai. Các phương thức gọi lại không được ghi đè sẽ không hoạt động.

Dưới đây là ví dụ về cách triển khai 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
        ... 
    }
}

Để đăng ký lệnh gọi lại và nhận thông báo, hãy gọi registerConnectivityDiagnosticsCallback. Để huỷ đăng ký lệnh gọi lại và ngừng nhận thông báo, hãy gọi unregisterConnectivityDiagnosticsCallback.

Dưới đây là ví dụ về cách đăng ký và huỷ đăng ký 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);

Xác nhận kết quả

API Chẩn đoán khả năng kết nối được CTS kiểm thử bằng ConnectivityDiagnosticsManagerTest.