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

Connectivity Diagnostics API 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 kết nối cho những 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 thuộc quyền sở hữu hoặc quản lý của ứng dụng.

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

  • Ứng dụng của nhà mạng: Quản lý các mạng di động mà subId 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

Các lệnh gọi lại được gọi trong những 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 thử nghiệm 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ờ có tình trạng tắc nghẽn dữ liệu: Nghi ngờ có tình trạng tắc nghẽn dữ liệu (một tình trạng trong đó 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 dữ liệu bị tắc nghẽn đáng ngờ.

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

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

Triển khai

Để sử dụng Connectivity Diagnostics API, ứng dụng phải lấy một thực thể ConnectivityDiagnosticsManager từ nền tảng. Bạn nên dùng phiên bản này để đăng ký và huỷ đăng ký các hoạt động triển khai ConnectivityDiagnosticsCallback. Các phương thức gọi lại không bị ghi đè là các thao tác không có hiệu lực.

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ý các lệnh gọi lại và nhận thông báo, hãy gọi registerConnectivityDiagnosticsCallback. Để huỷ đăng ký các 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.