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

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

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

هناك ثلاث خطوات لعملية المسح الضوئي:

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

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

القيود

فرض الإصدار 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.

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

Android 9:

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

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

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

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

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

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

• إذا كان تطبيقك يستهدف الإصدار 10 من نظام التشغيل Android (المستوى 29 لواجهة برمجة التطبيقات) أو إصدارًا أحدث من حزمة تطوير البرامج (SDK)، يحصل تطبيقك على الإذن 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" للاختبار على الجهاز فقط (ضمن خيارات المطوّرين > الشبكة > تقييد البحث عن شبكات Wi-Fi).