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

الأذونات

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

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

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

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

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

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

نظام التشغيل 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().

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

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

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

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

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

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

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