Connectivity Diagnostics API

Connectivity Diagnostics API به برنامه‌هایی که مالک یا مدیریت شبکه‌ها هستند، مانند برنامه‌های حامل، برنامه‌های VPN، و برنامه‌های پیشنهادی Wi-Fi، اجازه می‌دهد تا اطلاعات اتصال شبکه تشخیصی را از چارچوب دریافت کنند. این برنامه‌ها می‌توانند تماس‌های برگشتی را ثبت کنند و اعلان‌هایی را با اطلاعات اتصال برای شبکه‌های تحت مالکیت یا مدیریت خود دریافت کنند. برنامه‌ها برای شبکه‌هایی که تحت مالکیت یا مدیریت برنامه نیستند، اعلان دریافت نمی‌کنند.

در زیر نمونه‌هایی از برنامه‌هایی هستند که شبکه‌ها را مدیریت می‌کنند یا مالک آن هستند:

  • برنامه‌های حامل: شبکه‌های تلفن همراهی را مدیریت کنید که subId آن‌ها دارای امتیازات اپراتور است.
  • برنامه‌های پیشنهادی Wi-Fi: دارای شبکه‌های Wi-Fi هستند که به سیستم پیشنهاد می‌کنند
  • برنامه‌های VPN: همه شبکه‌هایی را که 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 به سیستم را گزارش کرده است. شبکه و اتصال گزارش شده (چه برنامه معتقد باشد که شبکه اتصال را ارائه می دهد یا نه) به اشتراک گذاشته می شود.

پیاده سازی

برای استفاده از Connectivity Diagnostics API، یک برنامه باید یک نمونه ConnectivityDiagnosticsManager از پلتفرم دریافت کند. این نمونه باید برای ثبت و لغو ثبت اجرای ConnectivityDiagnosticsCallback استفاده شود. روش‌های برگشت به تماس که لغو نمی‌شوند، بدون عملیات هستند.

در زیر نمونه ای از اجرای 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 تست شده است.