Connectivity Diagnostics API

연결 진단 API를 사용하면 이동통신사 앱, VPN 앱 및 Wi-Fi 추천 앱과 같은 네트워크를 소유하거나 관리하는 앱이 프레임워크에서 네트워크 연결 진단 정보를 수신할 수 있습니다. 이러한 앱은 소유하거나 관리하는 네트워크의 연결 정보로 콜백을 등록하고 알림을 수신할 수 있습니다. 앱은 소유하거나 관리하지 않는 네트워크의 알림을 수신하지 않습니다.

다음은 네트워크를 관리하거나 소유하는 앱의 예입니다.

  • 이동통신사 앱: subId가 이동통신사 권한을 갖는 모바일 네트워크를 관리합니다.
  • Wi-Fi 추천 앱: 시스템에 추천되는 Wi-Fi 네트워크를 소유합니다.
  • VPN 앱: 활성 VPN에서만 사용하는 모든 네트워크를 관리합니다.

콜백은 다음과 같은 경우에 호출됩니다.

  • 네트워크 유효성 검사: 시스템에서 특정 네트워크 평가를 완료했습니다. 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 구현을 등록 및 등록 취소하는 데 사용되어야 합니다. 재정의되지 않은 콜백 메서드는 노옵스(no-ops)입니다.

다음은 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는 ConnectivityDiagnosticsManagerTest에서 테스트된 CTS입니다.