واجهة برمجة تطبيقات طلب شبكة 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" وOUI لعنوان 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);