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

يمكنك استخدام إمكانات البحث عن شبكات Wi-Fi التي توفّرها واجهة برمجة تطبيقات WifiManager للحصول على قائمة بنقاط وصول 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() استيفاء جميع الشروط التالية:

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