Connectivity Diagnostics API

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

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

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

پیاده‌سازی

برای استفاده از API مربوط به Connectivity Diagnostics، یک برنامه باید یک نمونه ConnectivityDiagnosticsManager از پلتفرم دریافت کند. این نمونه باید برای ثبت و لغو ثبت پیاده‌سازی‌های ConnectivityDiagnosticsCallback استفاده شود. متدهای Callback که override نشده‌اند، 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
        ... 
    }
}

برای ثبت callbackها و دریافت اعلان‌ها، تابع registerConnectivityDiagnosticsCallback را فراخوانی کنید. برای لغو ثبت callbackها و توقف دریافت اعلان‌ها، تابع 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 توسط ConnectivityDiagnosticsManagerTest آزمایش شده است.