API การวินิจฉัยการเชื่อมต่อ

Connectivity Diagnostics API ช่วยให้แอปที่เป็นเจ้าของหรือจัดการเครือข่าย เช่น แอปของผู้ให้บริการ แอป VPN และแอปคำแนะนำ Wi-Fi ได้รับข้อมูลการวินิจฉัยการเชื่อมต่อเครือข่ายจากเฟรมเวิร์ก แอปเหล่านี้จะลงทะเบียนการติดต่อกลับและรับการแจ้งเตือนพร้อมข้อมูลการเชื่อมต่อสำหรับเครือข่ายที่ตนเป็นเจ้าของหรือจัดการได้ แอปจะไม่ได้รับการแจ้งเตือนสำหรับเครือข่ายที่แอปไม่ได้เป็นเจ้าของหรือจัดการ

ตัวอย่างแอปที่จัดการหรือเป็นเจ้าของเครือข่ายมีดังนี้

  • แอปของผู้ให้บริการ: จัดการเครือข่ายมือถือที่ subId ของตนมีสิทธิ์ของผู้ให้บริการ
  • แอปแนะนำ Wi-Fi: เครือข่าย Wi-Fi ของตัวเองที่แอปแนะนำให้กับระบบ
  • แอป VPN: จัดการเครือข่ายทั้งหมดที่ VPN ของแอปใช้ แต่เฉพาะในกรณีที่เป็น VPN ที่ใช้งานอยู่

ระบบจะเรียกใช้ Callback ในกรณีต่อไปนี้

  • การตรวจสอบเครือข่าย: ระบบประเมินเครือข่ายที่ระบุเสร็จแล้ว ชั้นเรียน 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 เมธอด Callback ที่ไม่ได้ลบล้างจะใช้งานไม่ได้

ด้านล่างนี้คือตัวอย่างการใช้งาน 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);

การตรวจสอบความถูกต้อง

Connectivity Diagnostics API ได้รับการทดสอบ CTS โดย ConnectivityDiagnosticsManagerTest