نظرة عامة على البحث عن شبكات Wi-Fi

يمكنك استخدام إمكانات البحث عن شبكات Wi-Fi التي توفرها WifiManager API للحصول على قائمة نقاط وصول Wi-Fi التي تكون مرئية من الجهاز.

عملية البحث عن شبكات Wi-Fi

هناك ثلاث خطوات لعملية الفحص:

1. تسجيل مستمِع للبث في SCAN_RESULTS_AVAILABLE_ACTION، وهو ما يتم استدعاؤه عند اكتمال طلبات الفحص، وتوفير حالة النجاح/الفشل. بالنسبة إلى الأجهزة التي تعمل بنظام التشغيل Android 10 (مستوى واجهة برمجة التطبيقات 29) والإصدارات الأحدث، يجب مراعاة ما يلي: سيتم إرسال البث لأي بحث كامل عن شبكة Wi-Fi يتم إجراؤه على الجهاز من خلال المنصة أو التطبيقات الأخرى. يمكن للتطبيقات الاستماع بشكل سلبي إلى كل عمليات الفحص. البث باستخدام البث بدون إجراء مسح ضوئي تمتلكه.

2. طلب فحص باستخدام WifiManager.startScan() احرص على التحقّق من حالة إرجاع الطريقة، لأنّ الاتصال قد يتعذّر إتمامه. لأيٍّ من الأسباب التالية:

   • قد يتم تقييد طلبات الفحص بسبب العدد الكبير جدًا من عمليات الفحص في وقت قصير.
   • الجهاز غير نشِط لفترة قصيرة وتم إيقاف ميزة الفحص.
   • أبلغَت أجهزة Wi-Fi عن تعذُّر إجراء الفحص.

3. الحصول على نتائج الفحص باستخدام WifiManager.getScanResults() نتائج الفحص التي يتم عرضها هي أحدث النتائج التي تم تعديلها، والتي قد من عملية فحص سابقة إذا لم تكتمل عملية الفحص الحالية أو تنجح يعني ذلك أنّك قد تحصل على نتائج فحص قديمة في حال طلب هذه الطريقة. قبل الحصول على نموذج ناجح SCAN_RESULTS_AVAILABLE_ACTION البث.

تقدِّم التعليمة البرمجية التالية مثالاً على كيفية تنفيذ هذه الخطوات:

Kotlin

val wifiManager = context.getSystemService(Context.WIFI_SERVICE) as WifiManager

val wifiScanReceiver = object : BroadcastReceiver() {

  override fun onReceive(context: Context, intent: Intent) {
    val success = intent.getBooleanExtra(WifiManager.EXTRA_RESULTS_UPDATED, false)
    if (success) {
      scanSuccess()
    } else {
      scanFailure()
    }
  }
}

val intentFilter = IntentFilter()
intentFilter.addAction(WifiManager.SCAN_RESULTS_AVAILABLE_ACTION)
context.registerReceiver(wifiScanReceiver, intentFilter)

val success = wifiManager.startScan()
if (!success) {
  // scan failure handling
  scanFailure()
}

....

private fun scanSuccess() {
  val results = wifiManager.scanResults
  ... use new scan results ...
}

private fun scanFailure() {
  // handle failure: new scan did NOT succeed
  // consider using old scan results: these are the OLD results!
  val results = wifiManager.scanResults
  ... potentially use older scan results ...
}

Java

WifiManager wifiManager = (WifiManager)
                   context.getSystemService(Context.WIFI_SERVICE);

BroadcastReceiver wifiScanReceiver = new BroadcastReceiver() {
  @Override
  public void onReceive(Context c, Intent intent) {
    boolean success = intent.getBooleanExtra(
                       WifiManager.EXTRA_RESULTS_UPDATED, false);
    if (success) {
      scanSuccess();
    } else {
      // scan failure handling
      scanFailure();
    }
  }
};

IntentFilter intentFilter = new IntentFilter();
intentFilter.addAction(WifiManager.SCAN_RESULTS_AVAILABLE_ACTION);
context.registerReceiver(wifiScanReceiver, intentFilter);

boolean success = wifiManager.startScan();
if (!success) {
  // scan failure handling
  scanFailure();
}

....

private void scanSuccess() {
  List<ScanResult> results = wifiManager.getScanResults();
  ... use new scan results ...
}

private void scanFailure() {
  // handle failure: new scan did NOT succeed
  // consider using old scan results: these are the OLD results!
  List<ScanResult> results = wifiManager.getScanResults();
  ... potentially use older scan results ...
}

القيود

فرض Android 8.0 (المستوى 26 من واجهة برمجة التطبيقات) قيودًا بشأن الأذونات المعدل المسموح به لعمليات البحث عن شبكات Wi-Fi.

لتحسين أداء الشبكة والأمان وعمر البطارية، Android 9 (واجهة برمجة التطبيقات) المستوى 28) تقييد متطلبات الأذونات وتقييد تكرار عمليات البحث عن شبكات Wi-Fi.

الأذونات

ملاحظة: في كل قسم من الأقسام التالية التي تشير إلى أذونات تحديد الموقع الجغرافي أو جمع البيانات، لذا ضع في اعتبارك أنه عند تشغيل تطبيقك في الخلفية، يجب أن يكون الوصول إلى الموقع للوظائف الأساسية للتطبيق ويصحبها الإفصاح للمستخدمين.

Android 8.0 وAndroid 8.1:

تم إجراء مكالمة ناجحة إلى WifiManager.getScanResults() تتطلب أيًّا من الأذونات التالية:

• ACCESS_FINE_LOCATION
• ACCESS_COARSE_LOCATION
• CHANGE_WIFI_STATE

إذا لم يكن لدى تطبيق الاتصال أي من هذه الأذونات، يتعذّر الاتصال باستخدام SecurityException

أما على الأجهزة التي تعمل بنظام التشغيل Android 8.0 (المستوى 26 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يمكنك استخدام CompanionDeviceManager فحص الأجهزة المصاحبة المجاورة نيابةً عن تطبيقك بدون طلب إذن تحديد الموقع الجغرافي لمزيد من المعلومات عن هذا الخيار، يُرجى الاطّلاع على جهاز مصاحب الإقران.

نظام التشغيل Android 9:

تم إجراء مكالمة ناجحة إلى WifiManager.startScan() تتطلّب استيفاء جميع الشروط التالية:

• يتضمَّن تطبيقك ACCESS_FINE_LOCATION أو ACCESS_COARSE_LOCATION إذن.
• يتضمَّن تطبيقك CHANGE_WIFI_STATE إذن.
• يتم تفعيل خدمات الموقع الجغرافي على الجهاز (ضمن الإعدادات > الموقع الجغرافي).

نظام التشغيل Android 10 (المستوى 29 من واجهة برمجة التطبيقات) والإصدارات الأحدث:

تم إجراء مكالمة ناجحة إلى WifiManager.startScan() تتطلّب استيفاء جميع الشروط التالية:

• إذا كان تطبيقك يستهدِف حزمة تطوير البرامج (SDK) لنظام التشغيل Android 10 (المستوى 29 من واجهة برمجة التطبيقات) أو إصدارًا أحدث، يجب ضبط السياسة على ACCESS_FINE_LOCATION إذن.
• إذا كان تطبيقك يستهدِف حزمة تطوير برامج (SDK) أقدم من Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، ACCESS_COARSE_LOCATION أو ACCESS_FINE_LOCATION إذن.
• يحتوي تطبيقك على CHANGE_WIFI_STATE. إذن.
• تم تمكين خدمات الموقع على الجهاز (ضمن الإعدادات > الموقع الجغرافي.

للاتصال بنجاح WifiManager.getScanResults()، تأكَّد من استيفاء جميع الشروط التالية:

• إذا كان تطبيقك يستهدِف حزمة تطوير البرامج (SDK) لنظام التشغيل Android 10 (المستوى 29 من واجهة برمجة التطبيقات) أو إصدارًا أحدث، يجب ضبط السياسة على لديه إذن ACCESS_FINE_LOCATION.
• إذا كان تطبيقك يستهدِف حزمة تطوير برامج (SDK) أقدم من Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، لديه إذن ACCESS_COARSE_LOCATION أو ACCESS_FINE_LOCATION.
• يتضمَّن تطبيقك ACCESS_WIFI_STATE إذن.
• تم تمكين خدمات الموقع على الجهاز (ضمن الإعدادات > الموقع الجغرافي.

إذا لم يستوفِ تطبيق الاتصال جميع هذه المتطلبات، لن يتم إجراء المكالمة: SecurityException

تقييد

تنطبق القيود التالية على معدل تكرار عمليات الفحص باستخدام WifiManager.startScan()

Android 8.0 وAndroid 8.1:

يمكن لكل تطبيق في الخلفية فحصه مرة واحدة خلال فترة 30 دقيقة.

نظام التشغيل Android 9:

يمكن لكل تطبيق يعمل في المقدّمة إجراء الفحص أربع مرات خلال دقيقتين. يسمح هذا عمليات الفحص في وقت قصير.

يمكن لجميع تطبيقات الخلفية معًا إجراء فحص مرة واحدة خلال 30 دقيقة.

نظام التشغيل Android 10 والإصدارات الأحدث:

وتنطبق حدود التقييد نفسها التي ينص عليها Android 9. يتوفّر خيار جديد للمطوّرين لإيقاف التقييد للاختبار المحلي (ضمن خيارات المطوّرين > الشبكات > تقييد البحث عن شبكات Wi-Fi).