واجهة برمجة تطبيقات طلب شبكة 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() في كائن معاودة الاتصال.

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

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

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

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

يوضِّح نموذج الرمز البرمجي التالي كيفية الاتصال بشبكة مفتوحة باستخدام البادئة "test" لمعرّف SSID ومعرّف مجموعة الخدمات الأساسية (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);