نظرة عامة على البحث عن شبكات 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 ...
}

القيود

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

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

الأذونات

الإصداران 8.0 و8.1 من نظام التشغيل Android:

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

إذا لم يستوفِ تطبيق الاتصال جميع هذه المتطلبات، ستتعذّر المكالمة وسيظهر الرمز SecurityException.

التقييد

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

الإصداران 8.0 و8.1 من نظام التشغيل Android:

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

Android 9:

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

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

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

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