Skip to content

Expose the GATT status on characteristic and descriptor failures - #41

Merged
newky2k merged 1 commit into
feature/bond-requestfrom
feature/gatt-status
Oct 15, 2026
Merged

newky2k merged 1 commit into
feature/bond-requestfrom
feature/gatt-status

Conversation

@newky2k

@newky2k newky2k commented Oct 15, 2026

Copy link
Copy Markdown
Owner

Fixes #36.

Stacked on #40 (feature/bond-request, issue #35), which is itself stacked on #39 (issue #34). This PR merges after #40, and #40 after #39. GitHub retargets each one as the PR below it is merged. The code here does not depend on #39 or #40; it is stacked only so the README and release-note edits do not conflict. The diff shows only the #36 change.

Public API (additive only)

  • enum GattFailure { None, Other, InsufficientAuthentication, InsufficientAuthorization, InsufficientEncryption }
  • interface IGattStatusException { int? GattStatus; GattFailure GattFailure; }, implemented by CharacteristicReadException, CharacteristicWriteException, DescriptorReadException and DescriptorWriteException, so one catch covers all four:
    catch (BleException ex) when (ex is IGattStatusException { GattFailure: GattFailure.InsufficientAuthentication or GattFailure.InsufficientEncryption })
  • On each of the four: GattStatus (int?), GattFailure, and a new constructor overload taking gattStatus after nativeStatus.

Where the status comes from

Platform GattStatus
Android The GattStatus from OnCharacteristicRead, OnCharacteristicWrite, OnDescriptorRead and OnDescriptorWrite
Apple platforms The NSError code, only when its domain is CBATTErrorDomain (CBATTError values are ATT codes). null for any other domain
Windows The ATT protocol error already reported by the read and write results

A refused subscription arrives as DescriptorWriteException on Android, because the library writes the configuration descriptor itself, and as CharacteristicReadException on Apple platforms. Both carry the status. GattStatus is null (GattFailure.None) where no status exists: the operation could not start, or the device disconnected.

Unchanged, on purpose

  • Exception types and messages are unchanged.
  • NativeStatus keeps its meaning. On Apple platforms it is still the NSError code whatever the domain, which is why the ATT-only value is a separate property rather than a reinterpretation of it.
  • The existing constructors behave exactly as before and leave GattStatus null.
  • The optional derived CharacteristicAuthenticationException from the issue is not added. Read, write and descriptor failures have no common base below BleException, and a derived type of one of them would not catch the others. The interface gives the single catch instead.
  • Android's internal GATT layer can report its own codes, such as 0x85 (GATT_ERROR). These are GattFailure.Other with the raw value in GattStatus. No mapping of stack-specific codes to the security failures is guessed at.

README / release notes

The README Bonding section gains "Recognising a security failure", with the catch example and the per-platform subscribe note. PackageReleaseNotes extends the "Unreleased" paragraph.

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. macos and tvos were not built locally (workloads not installed).
  • A consumer against net10.0 checks the classification of 0x05, 0x08, 0x0F and a raw 0x85, that the existing constructors leave GattStatus null with NativeStatus and messages unchanged, and that the interface catch pattern works.
  • Not tested on hardware. No refused read, write or subscribe has been produced against a real peripheral on Android or iOS, so the acceptance criteria need a manual check.
  • There is no test project in the repository, so no automated tests were added.

CharacteristicReadException, CharacteristicWriteException,
DescriptorReadException and DescriptorWriteException gain GattStatus, the
GATT status code where one was reported, and GattFailure, which
classifies it as InsufficientAuthentication (0x05), InsufficientAuthorization
(0x08), InsufficientEncryption (0x0F), Other or None. All four implement
the new IGattStatusException, so one catch can recognise a security
failure from any of them.

Android passes the GattStatus from the read, write and descriptor
callbacks. Apple platforms pass the NSError code only when its domain is
CBATTErrorDomain, because CBError codes in other domains mean something
else. Windows passes the ATT protocol error it already reported.

NativeStatus keeps its earlier meaning, including the NSError code
whatever its domain on Apple platforms, and every message is unchanged.
The new value is set through an added constructor overload, so the
existing constructors behave exactly as before.

Fixes #36
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