API Reference
SimpleCBLE function signatures, error handling, and ownership rules.
Include <simplecble/simplecble.h> for the complete C API. See the tutorial for working examples and the migration guide for changes from the previous API.
Calling convention
Functions with an out_error parameter require the address of an error variable initialized to NULL. They release its previous error, then leave it NULL on success or fill it on failure. Inspect the error before reusing the variable. A zero, false, or NULL result alone does not identify failure. Release the final error with simpleble_error_release(&error).
Callback setters without out_error require valid handles. Pass NULL as the callback to unregister it. Notification subscriptions and advanced Dongl pairing setters are fallible and retain out_error.
Data types and ownership
| Result | Release with |
|---|---|
| Allocated identifiers, addresses, read buffers, and local characteristic values | simpleble_free(pointer) |
| Error object | simpleble_error_release(&error) |
| Backend, adapter, or remote peripheral handle | The matching simpleble_*_release_handle(handle) |
| Local peripheral, service, or characteristic handle | The matching simpleble_local_*_release_handle(handle) |
| Service snapshot, including its payload, characteristics, and descriptors | simpleble_service_release(&service) |
| Manufacturer data snapshot | simpleble_manufacturer_data_release(&data) |
Service and manufacturer structs use allocated arrays with lengths/counts. Empty arrays have a zero count and a NULL pointer. Their release functions free the contents and zero the caller-owned struct. Release a result before filling the same struct again. Characteristics and descriptors inside a service belong to that service; copying a struct does not duplicate its allocations.
simpleble_uuid_t remains a value type containing char value[37]: space for a UUID string and its NUL terminator. Remote characteristic capabilities are the five can_* boolean fields. Local characteristic capabilities use the SIMPLEBLE_LOCAL_CHARACTERISTIC_* bit flags combined with |.
Error messages, version strings, native pointers, and callback payloads are borrowed. Scan-found and scan-updated callbacks are the exception for handles: each call transfers an owned peripheral handle that the application must release. Other callback handles refer to the object used for registration.
General
General
simplecble.h
void simpleble_free(void* handle)utils.h
simpleble_os_t simpleble_get_operating_system(void)const char* simpleble_get_version(void)Errors
Errors
simpleble_err_t classifies failures; test the error pointer for success.
| Code | Meaning |
|---|---|
SIMPLEBLE_ERROR_INVALID_ARGUMENT | A required argument is NULL or otherwise invalid. |
SIMPLEBLE_ERROR_OUT_OF_MEMORY | Memory allocation failed during an operation. |
SIMPLEBLE_ERROR_OBJECT_NOT_INITIALIZED | A SimpleBLE object has not been initialized. |
SIMPLEBLE_ERROR_INVALID_BACKEND_REFERENCE | An internal object reference cannot be resolved. |
SIMPLEBLE_ERROR_PERIPHERAL_NOT_CONNECTED | A GATT read, write, subscription, or unsubscription requires a connected peripheral. |
SIMPLEBLE_ERROR_GATT_SERVICE_NOT_FOUND | The requested service UUID is absent from the discovered GATT services. |
SIMPLEBLE_ERROR_GATT_CHARACTERISTIC_NOT_FOUND | The requested characteristic UUID is absent from the selected GATT service. |
SIMPLEBLE_ERROR_GATT_DESCRIPTOR_NOT_FOUND | The requested descriptor UUID is absent from the selected GATT characteristic. |
SIMPLEBLE_ERROR_OPERATION_NOT_SUPPORTED | The requested operation is not supported by the adapter or characteristic, or is unavailable in the library implementation. |
SIMPLEBLE_ERROR_OPERATION_FAILED | An operation failed without a more specific exception classification. |
SIMPLEBLE_ERROR_WINRT_ACCESS_DENIED | Retrieving a WinRT asynchronous result raised hresult_access_denied. |
SIMPLEBLE_ERROR_WINRT_EXCEPTION | Retrieving a WinRT asynchronous result raised another hresult_error. |
SIMPLEBLE_ERROR_CORE_BLUETOOTH_EXCEPTION | A CoreBluetoothException containing a diagnostic message. |
SIMPLEBLE_ERROR_UNCLASSIFIED_EXCEPTION | An exception has no dedicated error classification. |
SIMPLEBLE_ERROR_ADAPTER_IN_USE | The adapter is held by another process, such as a Dongl whose serial port another program has open. |
error.h
simpleble_err_t simpleble_error_code(const simpleble_error_t* error)const char* simpleble_error_message(const simpleble_error_t* error)void simpleble_error_release(simpleble_error_t** error)Backends
Backends
backend.h
size_t simpleble_backend_get_count(simpleble_error_t** out_error)simpleble_backend_t simpleble_backend_get_handle(size_t index, simpleble_error_t** out_error)simpleble_backend_t simpleble_backend_get_native(simpleble_error_t** out_error)simpleble_backend_t simpleble_backend_get_dongl(simpleble_error_t** out_error)simpleble_backend_t simpleble_backend_get_simulator(simpleble_error_t** out_error)void simpleble_backend_release_handle(simpleble_backend_t handle)char* simpleble_backend_identifier(simpleble_backend_t handle, simpleble_error_t** out_error)bool simpleble_backend_is_bluetooth_enabled(simpleble_backend_t handle, simpleble_error_t** out_error)size_t simpleble_backend_get_adapters_count(simpleble_backend_t handle, simpleble_error_t** out_error)simpleble_adapter_t simpleble_backend_get_adapters_handle(simpleble_backend_t handle, size_t index, simpleble_error_t** out_error)Adapters
Adapters
adapter.h
bool simpleble_adapter_is_bluetooth_enabled(simpleble_error_t** out_error)size_t simpleble_adapter_get_count(simpleble_error_t** out_error)simpleble_adapter_t simpleble_adapter_get_handle(size_t index, simpleble_error_t** out_error)void simpleble_adapter_release_handle(simpleble_adapter_t handle)void* simpleble_adapter_underlying(simpleble_adapter_t handle, simpleble_error_t** out_error)char* simpleble_adapter_identifier(simpleble_adapter_t handle, simpleble_error_t** out_error)char* simpleble_adapter_address(simpleble_adapter_t handle, simpleble_error_t** out_error)void simpleble_adapter_power_on(simpleble_adapter_t handle, simpleble_error_t** out_error)void simpleble_adapter_power_off(simpleble_adapter_t handle, simpleble_error_t** out_error)bool simpleble_adapter_is_powered(simpleble_adapter_t handle, simpleble_error_t** out_error)void simpleble_adapter_set_callback_on_power_on( simpleble_adapter_t handle, void (*callback)(simpleble_adapter_t adapter, void* userdata), void* userdata)void simpleble_adapter_set_callback_on_power_off( simpleble_adapter_t handle, void (*callback)(simpleble_adapter_t adapter, void* userdata), void* userdata)void simpleble_adapter_scan_start(simpleble_adapter_t handle, simpleble_error_t** out_error)void simpleble_adapter_scan_stop(simpleble_adapter_t handle, simpleble_error_t** out_error)bool simpleble_adapter_scan_is_active(simpleble_adapter_t handle, simpleble_error_t** out_error)void simpleble_adapter_scan_for(simpleble_adapter_t handle, int timeout_ms, simpleble_error_t** out_error)size_t simpleble_adapter_scan_get_results_count(simpleble_adapter_t handle, simpleble_error_t** out_error)simpleble_peripheral_t simpleble_adapter_scan_get_results_handle(simpleble_adapter_t handle, size_t index, simpleble_error_t** out_error)size_t simpleble_adapter_get_paired_peripherals_count(simpleble_adapter_t handle, simpleble_error_t** out_error)simpleble_peripheral_t simpleble_adapter_get_paired_peripherals_handle(simpleble_adapter_t handle, size_t index, simpleble_error_t** out_error)size_t simpleble_adapter_get_connected_peripherals_count(simpleble_adapter_t handle, simpleble_error_t** out_error)simpleble_peripheral_t simpleble_adapter_get_connected_peripherals_handle( simpleble_adapter_t handle, size_t index, simpleble_error_t** out_error)void simpleble_adapter_set_callback_on_scan_start( simpleble_adapter_t handle, void (*callback)(simpleble_adapter_t adapter, void* userdata), void* userdata)void simpleble_adapter_set_callback_on_scan_stop( simpleble_adapter_t handle, void (*callback)(simpleble_adapter_t adapter, void* userdata), void* userdata)void simpleble_adapter_set_callback_on_scan_updated( simpleble_adapter_t handle, void (*callback)(simpleble_adapter_t adapter, simpleble_peripheral_t peripheral, void* userdata), void* userdata)void simpleble_adapter_set_callback_on_scan_found( simpleble_adapter_t handle, void (*callback)(simpleble_adapter_t adapter, simpleble_peripheral_t peripheral, void* userdata), void* userdata)simpleble_local_peripheral_t simpleble_adapter_create_local_peripheral(simpleble_adapter_t handle, simpleble_error_t** out_error)Peripherals and returned data
Peripherals and returned data
peripheral.h
void simpleble_peripheral_release_handle(simpleble_peripheral_t handle)void* simpleble_peripheral_underlying(simpleble_peripheral_t handle, simpleble_error_t** out_error)char* simpleble_peripheral_identifier(simpleble_peripheral_t handle, simpleble_error_t** out_error)char* simpleble_peripheral_address(simpleble_peripheral_t handle, simpleble_error_t** out_error)simpleble_address_type_t simpleble_peripheral_address_type(simpleble_peripheral_t handle, simpleble_error_t** out_error)int16_t simpleble_peripheral_rssi(simpleble_peripheral_t handle, simpleble_error_t** out_error)int16_t simpleble_peripheral_tx_power(simpleble_peripheral_t handle, simpleble_error_t** out_error)uint16_t simpleble_peripheral_mtu(simpleble_peripheral_t handle, simpleble_error_t** out_error)void simpleble_peripheral_connect(simpleble_peripheral_t handle, simpleble_error_t** out_error)void simpleble_peripheral_disconnect(simpleble_peripheral_t handle, simpleble_error_t** out_error)bool simpleble_peripheral_is_connected(simpleble_peripheral_t handle, simpleble_error_t** out_error)bool simpleble_peripheral_is_connectable(simpleble_peripheral_t handle, simpleble_error_t** out_error)bool simpleble_peripheral_is_paired(simpleble_peripheral_t handle, simpleble_error_t** out_error)void simpleble_peripheral_unpair(simpleble_peripheral_t handle, simpleble_error_t** out_error)size_t simpleble_peripheral_services_count(simpleble_peripheral_t handle, simpleble_error_t** out_error)void simpleble_peripheral_services_get(simpleble_peripheral_t handle, size_t index, simpleble_service_t* out_service, simpleble_error_t** out_error)void simpleble_service_release(simpleble_service_t* service)size_t simpleble_peripheral_manufacturer_data_count(simpleble_peripheral_t handle, simpleble_error_t** out_error)void simpleble_peripheral_manufacturer_data_get(simpleble_peripheral_t handle, size_t index, simpleble_manufacturer_data_t* out_data, simpleble_error_t** out_error)void simpleble_manufacturer_data_release(simpleble_manufacturer_data_t* data)uint8_t* simpleble_peripheral_read(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, size_t* data_length, simpleble_error_t** out_error)void simpleble_peripheral_write_request(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, const uint8_t* data, size_t data_length, simpleble_error_t** out_error)void simpleble_peripheral_write_command(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, const uint8_t* data, size_t data_length, simpleble_error_t** out_error)void simpleble_peripheral_notify( simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, void (*callback)(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, const uint8_t* data, size_t data_length, void* userdata), void* userdata, simpleble_error_t** out_error)void simpleble_peripheral_indicate( simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, void (*callback)(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, const uint8_t* data, size_t data_length, void* userdata), void* userdata, simpleble_error_t** out_error)void simpleble_peripheral_unsubscribe(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, simpleble_error_t** out_error)uint8_t* simpleble_peripheral_read_descriptor(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, simpleble_uuid_t descriptor, size_t* data_length, simpleble_error_t** out_error)void simpleble_peripheral_write_descriptor(simpleble_peripheral_t handle, simpleble_uuid_t service, simpleble_uuid_t characteristic, simpleble_uuid_t descriptor, const uint8_t* data, size_t data_length, simpleble_error_t** out_error)void simpleble_peripheral_set_callback_on_connected( simpleble_peripheral_t handle, void (*callback)(simpleble_peripheral_t peripheral, void* userdata), void* userdata)void simpleble_peripheral_set_callback_on_disconnected( simpleble_peripheral_t handle, void (*callback)(simpleble_peripheral_t peripheral, void* userdata), void* userdata)Local peripheral hosting
Local peripheral hosting
local/peripheral.h
void simpleble_local_peripheral_release_handle(simpleble_local_peripheral_t handle)void* simpleble_local_peripheral_underlying(simpleble_local_peripheral_t handle, simpleble_error_t** out_error)void simpleble_local_peripheral_add_advertised_service(simpleble_local_peripheral_t handle, simpleble_uuid_t service, simpleble_error_t** out_error)void simpleble_local_peripheral_set_advertised_manufacturer_data(simpleble_local_peripheral_t handle, uint16_t company_id, const uint8_t* data, size_t data_length, simpleble_error_t** out_error)void simpleble_local_peripheral_set_connectable(simpleble_local_peripheral_t handle, bool connectable, simpleble_error_t** out_error)simpleble_local_service_t simpleble_local_peripheral_add_service(simpleble_local_peripheral_t handle, simpleble_uuid_t uuid, simpleble_error_t** out_error)size_t simpleble_local_peripheral_services_count(simpleble_local_peripheral_t handle, simpleble_error_t** out_error)simpleble_local_service_t simpleble_local_peripheral_services_get(simpleble_local_peripheral_t handle, size_t index, simpleble_error_t** out_error)void simpleble_local_peripheral_remove_all_services(simpleble_local_peripheral_t handle, simpleble_error_t** out_error)void simpleble_local_peripheral_start(simpleble_local_peripheral_t handle, simpleble_error_t** out_error)void simpleble_local_peripheral_stop(simpleble_local_peripheral_t handle, simpleble_error_t** out_error)bool simpleble_local_peripheral_is_started(simpleble_local_peripheral_t handle, simpleble_error_t** out_error)bool simpleble_local_peripheral_is_advertising(simpleble_local_peripheral_t handle, simpleble_error_t** out_error)void simpleble_local_peripheral_set_callback_on_client_connected( simpleble_local_peripheral_t handle, void (*callback)(simpleble_local_peripheral_t handle, const char* client_address, void* userdata), void* userdata)void simpleble_local_peripheral_set_callback_on_client_disconnected( simpleble_local_peripheral_t handle, void (*callback)(simpleble_local_peripheral_t handle, const char* client_address, void* userdata), void* userdata)Local services
Local services
local/service.h
void simpleble_local_service_release_handle(simpleble_local_service_t handle)size_t simpleble_local_service_characteristics_count(simpleble_local_service_t handle, simpleble_error_t** out_error)simpleble_local_characteristic_t simpleble_local_service_characteristics_get( simpleble_local_service_t handle, size_t index, simpleble_error_t** out_error)void simpleble_local_service_uuid(simpleble_local_service_t handle, simpleble_uuid_t* out_uuid, simpleble_error_t** out_error)simpleble_local_characteristic_t simpleble_local_service_add_characteristic( simpleble_local_service_t handle, simpleble_uuid_t uuid, uint32_t capabilities, simpleble_error_t** out_error)Local characteristics
Local characteristics
local/characteristic.h
void simpleble_local_characteristic_release_handle(simpleble_local_characteristic_t handle)void simpleble_local_characteristic_uuid(simpleble_local_characteristic_t handle, simpleble_uuid_t* out_uuid, simpleble_error_t** out_error)uint32_t simpleble_local_characteristic_capabilities(simpleble_local_characteristic_t handle, simpleble_error_t** out_error)uint8_t* simpleble_local_characteristic_value(simpleble_local_characteristic_t handle, size_t* data_length, simpleble_error_t** out_error)void simpleble_local_characteristic_set_value(simpleble_local_characteristic_t handle, const uint8_t* data, size_t data_length, simpleble_error_t** out_error)void simpleble_local_characteristic_set_callback_on_read( simpleble_local_characteristic_t handle, const uint8_t* (*callback)(simpleble_local_characteristic_t handle, size_t* data_length, void* userdata), void* userdata)void simpleble_local_characteristic_set_callback_on_write( simpleble_local_characteristic_t handle, void (*callback)(simpleble_local_characteristic_t handle, const uint8_t* data, size_t data_length, void* userdata), void* userdata)void simpleble_local_characteristic_set_callback_on_subscribed( simpleble_local_characteristic_t handle, void (*callback)(simpleble_local_characteristic_t handle, void* userdata), void* userdata)void simpleble_local_characteristic_set_callback_on_unsubscribed( simpleble_local_characteristic_t handle, void (*callback)(simpleble_local_characteristic_t handle, void* userdata), void* userdata)Advanced APIs
Advanced APIs
Dongl functions require a Dongl peripheral. The macOS, iOS, Linux, and Android functions are provided by their corresponding native backend builds. Apple cached-peripheral lookup accepts one identifier and returns an owned handle, or NULL without an error when no match is found.
advanced.h
void simpleble_advanced_dongl_set_passkey_request_callback( simpleble_peripheral_t handle, bool (*callback)(simpleble_peripheral_t handle, char passkey[7], void* userdata), void* userdata, simpleble_error_t** out_error)void simpleble_advanced_dongl_set_passkey_display_callback( simpleble_peripheral_t handle, void (*callback)(simpleble_peripheral_t handle, const char* passkey, void* userdata), void* userdata, simpleble_error_t** out_error)void simpleble_advanced_dongl_set_numeric_comparison_callback( simpleble_peripheral_t handle, bool (*callback)(simpleble_peripheral_t handle, const char* passkey, void* userdata), void* userdata, simpleble_error_t** out_error)void simpleble_advanced_macos_set_advertisement_local_name(simpleble_local_peripheral_t handle, const char* local_name, simpleble_error_t** out_error)simpleble_peripheral_t simpleble_advanced_macos_retrieve_cached_peripheral( simpleble_adapter_t handle, const char* identifier, simpleble_error_t** out_error)void simpleble_advanced_ios_set_advertisement_local_name(simpleble_local_peripheral_t handle, const char* local_name, simpleble_error_t** out_error)simpleble_peripheral_t simpleble_advanced_ios_retrieve_cached_peripheral( simpleble_adapter_t handle, const char* identifier, simpleble_error_t** out_error)void simpleble_advanced_linux_set_advertisement_local_name(simpleble_local_peripheral_t handle, const char* local_name, simpleble_error_t** out_error)JavaVM* simpleble_advanced_android_get_jvm(simpleble_error_t** out_error)void simpleble_advanced_android_set_jvm(JavaVM* jvm, simpleble_error_t** out_error)void simpleble_advanced_android_set_context(jobject context, simpleble_error_t** out_error)Configuration
Configuration
Set configuration before the first backend or adapter enumeration. These settings and logging functions do not use error objects.
config.h
void simpleble_config_reset_all(void)void simpleble_config_simplebluez_reset(void)bool simpleble_config_simplebluez_get_use_system_bus(void)void simpleble_config_simplebluez_set_use_system_bus(bool enabled)int64_t simpleble_config_simplebluez_get_connection_timeout_ms(void)void simpleble_config_simplebluez_set_connection_timeout_ms(int64_t timeout_ms)int64_t simpleble_config_simplebluez_get_disconnection_timeout_ms(void)void simpleble_config_simplebluez_set_disconnection_timeout_ms(int64_t timeout_ms)void simpleble_config_winrt_reset(void)bool simpleble_config_winrt_get_experimental_use_own_mta_apartment(void)void simpleble_config_winrt_set_experimental_use_own_mta_apartment(bool enabled)bool simpleble_config_winrt_get_experimental_reinitialize_winrt_apartment_on_main_thread(void)void simpleble_config_winrt_set_experimental_reinitialize_winrt_apartment_on_main_thread( bool enabled)bool simpleble_config_winrt_get_use_deferred_disconnect(void)void simpleble_config_winrt_set_use_deferred_disconnect(bool enabled)void simpleble_config_corebluetooth_reset(void)void simpleble_config_android_reset(void)simpleble_config_android_connection_priority_t simpleble_config_android_get_connection_priority(void)void simpleble_config_android_set_connection_priority( simpleble_config_android_connection_priority_t priority)void simpleble_config_set_android_connection_priority(int priority)void simpleble_config_dongl_reset(void)bool simpleble_config_dongl_get_use_dongl_backend(void)void simpleble_config_dongl_set_use_dongl_backend(bool enabled)bool simpleble_config_dongl_get_auto_update(void)void simpleble_config_dongl_set_auto_update(bool enabled)bool simpleble_config_dongl_get_force_update(void)void simpleble_config_dongl_set_force_update(bool enabled)Logging
Logging
logging.h
void simpleble_logging_set_level(simpleble_log_level_t level)simpleble_log_level_t simpleble_logging_get_level(void)void simpleble_logging_set_callback(simpleble_log_callback_t callback)bool simpleble_logging_has_callback(void)void simpleble_logging_log_default_stdout(void)void simpleble_logging_log_default_file(void)void simpleble_logging_log_default_file_path(const char* path)