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

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

لاستخدام واجهة برمجة التطبيقات هذه، اتّبِع الخطوات التالية:

1. أنشئ محددًا لشبكة Wi-Fi باستخدام WifiNetworkSpecifier.Builder.

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

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

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

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

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

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

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

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

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

نموذج رمز

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

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);