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

تقدّم التعليمة البرمجية التالية مثالاً على كيفية تنفيذ هذه الخطوات:

KotlinJava

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