Platform Notes
Native backends and advanced functionality available through SimpleCBLE.
The SimpleBLE platform notes also apply to the C API, including permission requirements, address formats, and connection behavior. Backend enumeration lets you select an implementation explicitly; it does not bypass OS permissions.
Advanced APIs
Include <simplecble/advanced.h> or the umbrella header. Native advanced functions are declared for their target platform and implemented when that native backend is built.
| Backend/platform | C API |
|---|---|
| Dongl | Passkey-entry, passkey-display, and numeric-comparison callback setters |
| macOS | simpleble_advanced_macos_set_advertisement_local_name() and simpleble_advanced_macos_retrieve_cached_peripheral() |
| iOS | simpleble_advanced_ios_set_advertisement_local_name() and simpleble_advanced_ios_retrieve_cached_peripheral() |
| Linux | simpleble_advanced_linux_set_advertisement_local_name() |
| Android | simpleble_advanced_android_get_jvm(), simpleble_advanced_android_set_jvm(), and simpleble_advanced_android_set_context() |
Apple cached-peripheral lookup accepts one CoreBluetooth identifier. It requires a powered-on adapter, does not scan, and does not guarantee reachability. An invalid or unknown identifier returns NULL without an error. Release a returned peripheral handle normally.
The advertised-name setters take a local peripheral handle. Configure the name before starting the host; NULL removes the override. They change the advertisement, not the system Bluetooth name.
Android local hosting
Provide the application's Java VM and application context before creating a local peripheral. Use the application context rather than an Activity context. The context setter retains a global JNI reference; get_jvm() returns a borrowed pointer. Each of these functions takes an error slot.
Dongl pairing
How the Dongl pairs and stores bonds is described in Pairing and bonding. Register pairing callbacks before connecting. Passkey entry writes six decimal digits plus a NUL terminator into the supplied seven-byte buffer and returns true; return false to reject pairing. Preserve leading zeroes.
Display and comparison callbacks receive a borrowed six-digit string. Numeric comparison returns true only when the user confirms the peer shows the same number. A missing entry or comparison callback rejects that request. These callbacks run on an internal worker thread and can obtain user input there.
The Dongl callback setters accept NULL to unregister and retain an error argument because a non-Dongl peripheral cannot accept these registrations.