K2GO-439 fix(hotspot): apply code-review findings on the NEARBY_WIFI slice

Point LocalHotspotManager's doc at HotspotPermissions (not FINE location); note
requiredFor assumes targetSdk >= 33; scope FINE/COARSE to maxSdkVersion 32 (NEARBY
covers 33+); and show the retry hint on permission-denied instead of a perpetual
"starting" (Connect and Clone), the hint now naming Wi-Fi and the permission (34 locales).

Author: luisguzman-adfa

controller/app/src/main/AndroidManifest.xml

@@ -6,10 +6,11 @@
     <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
     <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
     <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
-    <!-- ADFA-4520: LocalOnlyHotspot requires location at runtime on targetSdk 32 and below -->
-    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
-    <!-- K2GO-438: Android 12+ lets the user grant COARSE only, so declare it with FINE (CoarseFineLocation). -->
-    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <!-- ADFA-4520 / K2GO-439: location gated LocalOnlyHotspot only on API 32 and below; API 33+ uses
+         NEARBY_WIFI_DEVICES below, so scope FINE/COARSE (the hotspot is their only consumer) to API 32. -->
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="32" />
+    <!-- K2GO-438: Android 12 and below let the user grant COARSE only, so declare it with FINE (CoarseFineLocation). -->
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="32" />
     <!-- K2GO-439: targetSdk 33+ needs NEARBY_WIFI_DEVICES for startLocalOnlyHotspot (FINE only sufficed on 32 and below).
          neverForLocation: the hotspot does not derive location from Wi-Fi scans. -->
     <uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES"

controller/app/src/main/java/org/appdevforall/k2go/hotspot/HotspotPermissions.java

@@ -30,7 +30,11 @@ public static String[] required() {
         return requiredFor(Build.VERSION.SDK_INT);
     }
 
-    /** The rule as a pure function of the API level. Package-private for unit testing. */
+    /**
+     * The rule as a pure function of the API level. Package-private for unit testing.
+     * Keyed off the device API: startLocalOnlyHotspot bases its requirement on the app
+     * targetSdk, and keying off the device API matches only because the app targets >= 33.
+     */
     static String[] requiredFor(int sdkInt) {
         if (sdkInt >= Build.VERSION_CODES.TIRAMISU) {
             return new String[]{ Manifest.permission.NEARBY_WIFI_DEVICES };

controller/app/src/main/java/org/appdevforall/k2go/hotspot/LocalHotspotManager.java

@@ -8,8 +8,9 @@
  *               the carrier tethering-entitlement check, so it works with no SIM and
  *               no data plan. The reservation is process-bound: it stays up while this
  *               app process is alive and is torn down on close() or process death.
- *               API 26+ only; callers must gate on Build.VERSION and hold
- *               CHANGE_WIFI_STATE + ACCESS_FINE_LOCATION (with Location services on).
+ *               API 26+ only; callers must gate on Build.VERSION and hold CHANGE_WIFI_STATE
+ *               plus the hotspot permission from HotspotPermissions (NEARBY_WIFI_DEVICES on
+ *               API 33+, or ACCESS_FINE_LOCATION with Location services on 32 and below).
  *
  *               V1 scope (ADFA-4520): manual opt-in from Advanced settings, plus a
  *               contextual recommendation surfaced only when BOTH conditions hold
@@ -110,13 +111,15 @@ public boolean isOn() {
     }
 
     /**
-     * Starts a LocalOnlyHotspot. Caller must have already granted CHANGE_WIFI_STATE +
-     * ACCESS_FINE_LOCATION and enabled Location services; otherwise onFailed fires.
+     * Starts a LocalOnlyHotspot. Caller must have already granted CHANGE_WIFI_STATE and the
+     * hotspot permission (see HotspotPermissions); on API 32 and below that also needs Location
+     * services on. Otherwise onFailed fires.
      */
     // NewApi is suppressed because every API-26 reference below is protected by the
     // explicit Build.VERSION.SDK_INT guard (lint cannot see through isSupported(), and
     // @RequiresApi does not cover the anonymous callback class). MissingPermission is
-    // suppressed because CHANGE_WIFI_STATE + ACCESS_FINE_LOCATION are requested at runtime.
+    // suppressed because CHANGE_WIFI_STATE and the hotspot permission (HotspotPermissions) are
+    // requested at runtime.
     @SuppressLint({"MissingPermission", "NewApi"})
     public void start(Context context) {
         if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {

controller/app/src/main/java/org/appdevforall/k2go/redesign/CloneFragment.java

@@ -730,7 +730,10 @@ private void renderPrepare() {
                 secJoin.setFallback(requireContext(), null);
                 secJoin.caption.setText(getString(R.string.k2go_connect_hotspot_unsupported));
                 secJoin.subCaption.setText(getString(R.string.k2go_connect_try_wifi));
-            } else if (phase == LocalHotspotManager.Phase.FAILED) {
+            } else if (phase == LocalHotspotManager.Phase.FAILED
+                    || (phase != LocalHotspotManager.Phase.ON && !HotspotPermissions.granted(requireContext()))) {
+                // FAILED, or the hotspot permission is not granted (denied): show the hint instead of a
+                // perpetual "starting" placeholder (K2GO-439).
                 secJoin.frame.setVisibility(View.GONE);
                 secJoin.setFallback(requireContext(), null);
                 secJoin.caption.setText(getString(R.string.k2go_connect_hotspot_failed));

controller/app/src/main/java/org/appdevforall/k2go/redesign/ConnectFragment.java

@@ -216,7 +216,10 @@ private void renderHotspot() {
             singleStatus(getString(R.string.k2go_connect_hotspot_unsupported), getString(R.string.k2go_connect_try_wifi));
             return;
         }
-        if (phase == LocalHotspotManager.Phase.FAILED) {
+        // FAILED, or the hotspot permission is not granted (denied): show the hint instead of a
+        // perpetual "starting" placeholder (K2GO-439).
+        if (phase == LocalHotspotManager.Phase.FAILED
+                || (phase != LocalHotspotManager.Phase.ON && !HotspotPermissions.granted(requireContext()))) {
             singleStatus(getString(R.string.k2go_connect_hotspot_failed), getString(R.string.k2go_connect_enable_location));
             return;
         }

controller/app/src/main/res/values-ar/strings.xml

@@ -799,7 +799,7 @@
     <string name="k2go_connect_starting_hotspot">جارٍ بدء نقطة الاتصال…</string>
     <string name="k2go_connect_resolving_address">جارٍ العثور على عنوان نقطة الاتصال…</string>
     <string name="k2go_connect_hotspot_failed">تعذّر بدء نقطة الاتصال</string>
-    <string name="k2go_connect_enable_location">تأكد من تشغيل Wi-Fi، ثم حاول مرة أخرى.</string>
+    <string name="k2go_connect_enable_location">فعّل Wi-Fi وامنح الإذن، ثم حاول مرة أخرى.</string>
     <string name="k2go_connect_no_wifi">لست على شبكة Wi-Fi</string>
     <string name="k2go_connect_join_wifi">انضم إلى نفس شبكة Wi-Fi أو اتصل بنقطة اتصال المكتبة.</string>
     <string name="k2go_fallback_wifi">Wi-Fi: %1$s</string>

controller/app/src/main/res/values-az/strings.xml

@@ -819,7 +819,7 @@
     <string name="k2go_connect_starting_hotspot">Hotspot başladılır…</string>
     <string name="k2go_connect_resolving_address">Hotspot ünvanı tapılır…</string>
     <string name="k2go_connect_hotspot_failed">Hotspot başladıla bilmədi</string>
-    <string name="k2go_connect_enable_location">Wi-Fi-nin aktiv olduğundan əmin olun, sonra yenidən cəhd edin.</string>
+    <string name="k2go_connect_enable_location">Wi-Fi-ni yandırın və icazəni verin, sonra yenidən cəhd edin.</string>
     <string name="k2go_connect_no_wifi">Wi-Fi şəbəkəsində deyil</string>
     <string name="k2go_connect_join_wifi">Eyni Wi-Fi-yə və ya kitabxananın hotspotuna qoşulun.</string>
     <string name="k2go_fallback_wifi">Wi-Fi: %1$s</string>

controller/app/src/main/res/values-bg/strings.xml

@@ -806,7 +806,7 @@
     <string name="k2go_connect_starting_hotspot">Стартиране на точката за достъп…</string>
     <string name="k2go_connect_resolving_address">Търсене на адрес на точката за достъп…</string>
     <string name="k2go_connect_hotspot_failed">Неуспешно стартиране на точката за достъп</string>
-    <string name="k2go_connect_enable_location">Уверете се, че Wi-Fi е включен, след което опитайте отново.</string>
+    <string name="k2go_connect_enable_location">Включете Wi-Fi и дайте разрешението, след което опитайте отново.</string>
     <string name="k2go_connect_no_wifi">Не сте в Wi-Fi мрежа</string>
     <string name="k2go_connect_join_wifi">Свържете се със същата Wi-Fi или с точката за достъп на библиотеката.</string>
     <string name="k2go_fallback_wifi">Wi-Fi: %1$s</string>

controller/app/src/main/res/values-bn/strings.xml

@@ -812,7 +812,7 @@
     <string name="k2go_connect_starting_hotspot">হটস্পট শুরু হচ্ছে…</string>
     <string name="k2go_connect_resolving_address">হটস্পট ঠিকানা খোঁজা হচ্ছে…</string>
     <string name="k2go_connect_hotspot_failed">হটস্পট শুরু করা যায়নি</string>
-    <string name="k2go_connect_enable_location">Wi-Fi চালু আছে কিনা নিশ্চিত করুন, তারপর আবার চেষ্টা করুন।</string>
+    <string name="k2go_connect_enable_location">Wi-Fi চালু করুন এবং অনুমতি দিন, তারপর আবার চেষ্টা করুন।</string>
     <string name="k2go_connect_no_wifi">কোনো Wi-Fi নেটওয়ার্কে নেই</string>
     <string name="k2go_connect_join_wifi">একই Wi-Fi-তে বা লাইব্রেরির হটস্পটে যুক্ত হন।</string>
     <string name="k2go_fallback_wifi">Wi-Fi: %1$s</string>

controller/app/src/main/res/values-cs/strings.xml

@@ -806,7 +806,7 @@
     <string name="k2go_connect_starting_hotspot">Spouštění hotspotu…</string>
     <string name="k2go_connect_resolving_address">Hledání adresy hotspotu…</string>
     <string name="k2go_connect_hotspot_failed">Nepodařilo se spustit hotspot</string>
-    <string name="k2go_connect_enable_location">Zkontrolujte, že je Wi-Fi zapnutá, a zkuste to znovu.</string>
+    <string name="k2go_connect_enable_location">Zapněte Wi-Fi a udělte oprávnění, poté to zkuste znovu.</string>
     <string name="k2go_connect_no_wifi">Nepřipojeno k síti Wi-Fi</string>
     <string name="k2go_connect_join_wifi">Připoj se ke stejné Wi-Fi nebo k hotspotu knihovny.</string>
     <string name="k2go_fallback_wifi">Wi-Fi: %1$s</string>