واجهة برمجة تطبيقات طلب شبكة Wi-Fi للاتصال من خلال شبكة الند للند

على نظام التشغيل Android 10 (المستوى 29 لواجهة برمجة التطبيقات) والأجهزة الأحدث، يمكنك استخدام واجهة برمجة تطبيقات جديدة من نظير إلى نظير لتمهيد الإعداد للأجهزة الثانوية مثل Chromecast وأجهزة Google Home. تتيح هذه الميزة لتطبيقك أن تطلب من المستخدم تغيير نقطة الوصول التي يتصل بها الجهاز، وذلك باستخدام WifiNetworkSpecifier لوصف خصائص الشبكة المطلوبة.

لاستخدام واجهة برمجة التطبيقات هذه، يمكنك إجراء ما يلي:

1. يمكنك إنشاء محدِّد لشبكة Wi-Fi باستخدام WifiNetworkSpecifier.Builder.

2. يمكنك ضبط فلتر للشبكة لمطابقة الشبكات المطلوب الاتصال بها، بالإضافة إلى بيانات الاعتماد المطلوبة.

3. اختيار مجموعة من SSID وSSID pattern وBSSID وBSSID pattern لضبط فلتر الشبكة في كل طلب، مع مراعاة المتطلبات التالية:

   • يجب أن يقدّم كل طلب سمة واحدة على الأقل من SSID أو SSID pattern أو BSSID أو BSSID pattern
   • يمكن لكل طلب ضبط سمة واحدة فقط من SSID أو SSID pattern
   • يمكن لكل طلب ضبط سمة واحدة فقط من BSSID أو BSSID pattern

4. أضِف المحدّدات إلى طلب الشبكة مع مثيل NetworkCallback لتتبُّع حالة الطلب.

   إذا قبِل المستخدم الطلب وكان الاتصال بالشبكة ناجحًا، يتم استدعاء NetworkCallback.onAvailable() في عنصر الاستدعاء. إذا رفض المستخدم الطلب أو إذا تعذّر الاتصال بالشبكة، يتم استدعاء NetworkCallback.onUnavailable() في عنصر الاستدعاء.

يؤدي بدء طلب الاتصال بجهاز نظير إلى تشغيل مربع حوار على نفس الجهاز، ويمكن لمستخدم الجهاز قبول طلب الاتصال من خلاله.

ملاحظة: لا يؤدي إنشاء اتصال باستخدام واجهة برمجة التطبيقات هذه إلى توفير اتصال بالإنترنت للتطبيق أو بالجهاز. ولتوفير اتصال بالإنترنت للتطبيقات على الجهاز، استخدِم Wi-Fi Suggestion API بدلاً من ذلك.

تجاوز موافقة المستخدم

بعد موافقة المستخدم على شبكة للاتصال بها استجابةً لطلب من تطبيق معيّن، يحفظ الجهاز الموافقة لنقطة الوصول المحدّدة. إذا قدَّم التطبيق طلبًا محددًا للاتصال بنقطة الوصول هذه مرة أخرى، سيتخطّى الجهاز مرحلة موافقة المستخدم ويتصل تلقائيًا بالشبكة. وإذا اختار المستخدم نسيان بيانات الشبكة أثناء الاتصال بشبكة تطلبها واجهة برمجة التطبيقات، ستتم إزالة هذه الموافقة المخزَّنة لهذه المجموعة من التطبيق والشبكة، ويجب أن يوافق المستخدم مرة أخرى على أي طلب مستقبلي من التطبيق. إذا قدَّم التطبيق طلبًا غير محدَّد، مثل استخدام نمط SSID أو BSSID، يجب أن يوافق المستخدم على الطلب.

نموذج التعليمات البرمجية

يعرض نموذج الرمز التالي كيفية الاتصال بشبكة مفتوحة باستخدام بادئة SSID للمعرّف "test" ومعرّف مجموعة الخدمات الأساسية (BSSID) للمستخدم "10:03:23":

Kotlin

val specifier = WifiNetworkSpecifier.Builder()
    .setSsidPattern(PatternMatcher("test", PatternMatcher.PATTERN_PREFIX))
    .setBssidPattern(MacAddress.fromString("10:03:23:00:00:00"), MacAddress.fromString("ff:ff:ff:00:00:00"))
    .build()

val request = NetworkRequest.Builder()
    .addTransportType(NetworkCapabilities.TRANSPORT_WIFI)
    .removeCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
    .setNetworkSpecifier(specifier)
    .build()

val connectivityManager = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager

val networkCallback = object : ConnectivityManager.NetworkCallback() {
    ...
    override fun onAvailable(network: Network?) {
        // do success processing here..
    }

    override fun onUnavailable() {
        // do failure processing here..
    }
    ...
}
connectivityManager.requestNetwork(request, networkCallback)
...
// Release the request when done.
connectivityManager.unregisterNetworkCallback(networkCallback)

Java

final NetworkSpecifier specifier =
  new WifiNetworkSpecifier.Builder()
  .setSsidPattern(new PatternMatcher("test", PatternMatcher.PATTERN_PREFIX))
  .setBssidPattern(MacAddress.fromString("10:03:23:00:00:00"), MacAddress.fromString("ff:ff:ff:00:00:00"))
  .build();

final NetworkRequest request =
  new NetworkRequest.Builder()
  .addTransportType(NetworkCapabilities.TRANSPORT_WIFI)
  .removeCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
  .setNetworkSpecifier(specifier)
  .build();

final ConnectivityManager connectivityManager = (ConnectivityManager)
  context.getSystemService(Context.CONNECTIVITY_SERVICE);

final NetworkCallback networkCallback = new NetworkCallback() {
  ...
  @Override
  void onAvailable(...) {
      // do success processing here..
  }

  @Override
  void onUnavailable(...) {
      // do failure processing here..
  }
  ...
};
connectivityManager.requestNetwork(request, networkCallback);
...
// Release the request when done.
connectivityManager.unregisterNetworkCallback(networkCallback);