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

API Chẩn đoán 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 này. 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 các mạng mà chúng sở hữu hoặc quản lý. Ứng dụng sẽ không nhận được thông báo cho các 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ủ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 sử dụng, nhưng chỉ khi các mạng này 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 quy trình kiểm thử 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, một tình trạng trong đó các gói IP không lưu thông đúng cách qua mạng. Lớp DataStallReport cung cấp thông tin về các quầy dữ liệu đáng ngờ.

    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à kết nối được báo cáo (cho dù ứng dụng cho rằng mạng có cung cấp kết nối hay không) được chia sẻ.

Triển khai

Để sử dụng API Chẩn đoán kết nối, ứng dụng phải lấy một thực thể ConnectivityDiagnosticsManager từ nền tảng. Bạn nên sử dụng thực thể 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à 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 kết nối được ConnectivityDiagnosticsManagerTest kiểm tra CTS.