First-class Bluetooth: core API, all ports, simulator debugging and build detection

.ci/container/Dockerfile

@@ -14,6 +14,7 @@ RUN apt-get update && apt-get install -y \
     ant \
     maven \
     libncurses6 \
+    libdbus-1-3 \
     sudo \
     openjdk-17-jdk \
     openjdk-21-jdk \

.github/workflows/pr.yml

@@ -116,6 +116,20 @@ jobs:
           rm -rf maven/target/cn1-binaries
           mkdir -p maven/target
           cp -r /opt/cn1-binaries maven/target/cn1-binaries
+          # The container bakes a cn1-binaries snapshot at image-build time, so
+          # recently added native libraries lag until the image is rebuilt.
+          # Overlay a fresh ble/ from master (a small sparse/partial clone) so
+          # libcn1ble -- required by the JavaSE native-engine integration tests
+          # -- is present. Best-effort: a network hiccup leaves the baked copy.
+          rm -rf /tmp/cn1bin-ble
+          if git clone --no-checkout --depth 1 --filter=blob:none \
+                https://github.com/codenameone/cn1-binaries /tmp/cn1bin-ble \
+              && git -C /tmp/cn1bin-ble sparse-checkout set ble \
+              && git -C /tmp/cn1bin-ble checkout \
+              && [ -d /tmp/cn1bin-ble/ble ]; then
+            rm -rf maven/target/cn1-binaries/ble
+            cp -r /tmp/cn1bin-ble/ble maven/target/cn1-binaries/ble
+          fi
       - name: Run Maven plugin tests
         if: ${{ matrix.java-version == 8 }}
         working-directory: maven
@@ -127,6 +141,14 @@ jobs:
             -Dcodename1.platform=javase \
             -Dcn1.binaries="${CN1_BINARIES}" \
             -pl codenameone-maven-plugin -am -Plocal-dev-javase test
+      - name: Install native BLE runtime dependency (libdbus)
+        if: ${{ matrix.java-version == 8 }}
+        # libcn1ble.so (the JavaSE native Bluetooth backend) links libdbus-1
+        # for BlueZ, so it must be present for the native-engine integration
+        # tests to load the library. Also baked into the pr-ci-container image
+        # (.ci/container/Dockerfile); this step covers running against the
+        # previously published container before the rebuild propagates.
+        run: apt-get update -qq && apt-get install -y -qq libdbus-1-3
       - name: Run JavaSE port unit tests
         if: ${{ matrix.java-version == 8 }}
         # Surface regressions in the simulator-side helpers (CSSWatcher

CodenameOne/src/com/codename1/bluetooth/AdapterState.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codename1.bluetooth;
+
+/// Lifecycle states of the local Bluetooth adapter, a union of the Android
+/// `BluetoothAdapter` states and the iOS `CBManagerState` values. Query via
+/// [Bluetooth#getAdapterState()] and observe changes with
+/// [Bluetooth#addAdapterStateListener(AdapterStateListener)].
+public enum AdapterState {
+    /// The state has not been determined yet -- e.g. iOS before the first
+    /// CoreBluetooth manager callback fired.
+    UNKNOWN,
+
+    /// The device has no Bluetooth hardware, or the port does not implement
+    /// Bluetooth at all. The fallback base [Bluetooth] class always reports
+    /// this state.
+    UNSUPPORTED,
+
+    /// The app is not authorized to use Bluetooth (iOS privacy authorization
+    /// denied / restricted, or missing runtime permissions on Android).
+    UNAUTHORIZED,
+
+    /// The adapter is off. Ask the user to enable it, optionally via
+    /// [Bluetooth#requestEnable()].
+    POWERED_OFF,
+
+    /// The adapter is transitioning to [#POWERED_ON] (Android only; iOS
+    /// reports the transition as a direct state change).
+    TURNING_ON,
+
+    /// The adapter is on and ready for scanning, connections and
+    /// advertising.
+    POWERED_ON,
+
+    /// The adapter is transitioning to [#POWERED_OFF] (Android only).
+    TURNING_OFF
+}

CodenameOne/src/com/codename1/bluetooth/AdapterStateListener.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2012, Codename One and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Codename One designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Codename One through http://www.codenameone.com/ if you
+ * need additional information or have any questions.
+ */
+package com.codename1.bluetooth;
+
+/// Observes local adapter state changes registered via
+/// [Bluetooth#addAdapterStateListener(AdapterStateListener)]. Single
+/// abstract method so application code can pass a lambda. Always invoked on
+/// the EDT.
+public interface AdapterStateListener {
+    /// Fired on the EDT whenever the adapter transitions to a new
+    /// [AdapterState].
+    void adapterStateChanged(AdapterState newState);
+}