Skip to content

Expose a device's bond state and raise an event when it changes - #39

Merged
newky2k merged 1 commit into
developmentfrom
feature/bond-state
Oct 15, 2026
Merged

newky2k merged 1 commit into
developmentfrom
feature/bond-state

Conversation

@newky2k

@newky2k newky2k commented Oct 15, 2026 •

Copy link
Copy Markdown
Owner

Fixes #34.

Merges first. #40 (issue #35) is stacked on this PR, and #41 (issue #36) on #40. Merge this one, then #40, then #41.

Public API (additive only)

  • Device.BondState (DeviceBondState). Never throws.
  • Adapter.DeviceBondStateChanged (EventHandler<DeviceBondStateChangedEventArgs>), raised on Android.
  • DeviceBondState.Unknown, declared last so NotBonded, Bonding and Bonded keep their values (0, 1, 2).

Per platform

Platform BondState Event
Android From BluetoothDevice.BondState on every read Raised on the main thread for every ACTION_BOND_STATE_CHANGED broadcast
iOS, macOS, Mac Catalyst, tvOS Always Unknown Never raised
Windows Bonded / NotBonded from the device's pairing information Never raised
net10.0, netstandard2.0 Always Unknown Never raised

Unknown is also reported where the state cannot be read: Android 12+ without BLUETOOTH_CONNECT (the SecurityException is traced and swallowed), a stand-in device built through the protected constructor, and a disposed device.

Android receiver

  • The Android adapter registers BondStatusBroadcastReceiver in its constructor and unregisters it in Dispose. From API 33 it registers with RECEIVER_NOT_EXPORTED, which still receives the protected system broadcast. A registration failure is traced, not thrown: bond events are an addition to the adapter, not a condition of it working.
  • The device in the event is the instance the adapter already tracks (connected first, then discovered), so PropertyChanged for BondState fires on that instance too. An unknown device gets a new Device.
  • The receiver could not have worked before: it built a Device with a null adapter, which throws ArgumentNullException since 4.0. Its public surface (type, parameterless constructor, BondStateChanged event) is unchanged; the parameterless constructor resolves devices through BluetoothLE.Current.Adapter. OnReceive now catches its own failures, because it runs on the main looper.

README

New "Bonding" section with the table above, the Apple behaviour (the OS pairs on demand when a protected characteristic is first accessed; the app cannot query or request a bond; a stale bond is removed by the user in Settings), and the Android permission note.

Verification

  • Builds with 0 errors for netstandard2.0, net10.0, net10.0-android, net10.0-ios, net10.0-maccatalyst, net10.0-windows10.0.19041.0 and net481. No new warnings. net10.0-macos and net10.0-tvos were not built locally (workloads not installed); the Apple partial they use is the same file as iOS.
  • A consumer against net10.0 checks that a stand-in device reports Unknown, still does after Dispose, and that the existing enum values are unchanged.
  • Not tested on hardware. The Android receiver has not been run on a device, so the acceptance criteria for bond, bonding and unbond events need a manual check.
  • There is no test project in the repository, so no automated tests were added.

Notes for review

  • This adds public API, while the release workflow stamps 4.0.yyMM.n. Consider whether this release should move to 4.1.
  • PackageReleaseNotes gains an "Unreleased" paragraph to be given its version at release.

Device.BondState reports the bond (pairing) state as the platform sees it:
read from the system on Android, from the pairing information on Windows,
and Unknown on Apple platforms, where CoreBluetooth does not expose bonding.
DeviceBondState gains Unknown, declared last so the existing values do not
move. It is also reported where the state cannot be read: Android 12 and
later without BLUETOOTH_CONNECT, the platform-neutral targets, stand-in
devices and disposed devices. Reading the property never throws.

The Android adapter now registers BondStatusBroadcastReceiver for its
lifetime and raises Adapter.DeviceBondStateChanged, resolving the device
to the instance it already tracks so PropertyChanged fires for BondState
on that instance too. The receiver previously could not have worked: it
built a Device with a null adapter, which throws. It keeps its public
surface, and handles its own failures because OnReceive runs on the main
looper. Registration uses RECEIVER_NOT_EXPORTED from API 33 and is
undone when the adapter is disposed.

The README gains a Bonding section describing each platform, including
how pairing works on Apple platforms.

Fixes #34
@newky2k
newky2k merged commit 7f7400f into development Oct 15, 2026
1 check passed
@newky2k
newky2k deleted the feature/bond-state branch October 15, 2026 08:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant