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

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

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

تتضمّن عملية البحث ثلاث خطوات:

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

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

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

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

يوضّح الرمز التالي مثالاً على كيفية تنفيذ هذه الخطوات:

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 ...
}

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 ...
}

القيود

فرض الإصدار 8.0 من نظام التشغيل Android (المستوى 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.

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

‫Android 9:

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

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

الإصدار 10 من نظام التشغيل Android (المستوى 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 دقيقة.

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

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