---
title: API Reference
description: Reference for the SimpleCBLE C API.
---

import { ApiClass, ApiMethod, ApiSection } from "@/components/api";

The SimpleCBLE API provides a C-compatible interface for SimpleBLE. It relies on handles (`simpleble_adapter_t`, `simpleble_peripheral_t`) to manage objects.

<ApiSection title="General" id="general">

## Memory Management [#memory-management] [toc]

<ApiClass name="General Functions">

<ApiMethod
  signature="void simpleble_free(void* handle)"
  brief="Frees memory allocated by the library."
  detailed="This function must be used to free strings (char*) and other auxiliary memory returned by the library. Do NOT use it to free adapter or peripheral handles."
  parameters={[{"name":"handle","type":"void*"}]}
/>

</ApiClass>

</ApiSection>

<ApiSection title="Adapter" id="adapter">

## simpleble_adapter_t [#simpleble_adapter_t] [toc]

<ApiClass name="simpleble_adapter_t" detailed="Handle representing a physical Bluetooth adapter. You must release this handle using `simpleble_adapter_release_handle` when done.">

### Lifecycle and Info [!toc]

<ApiMethod
  signature="size_t simpleble_adapter_get_count(void)"
  brief="Get the number of available adapters."
/>

<ApiMethod
  signature="simpleble_adapter_t simpleble_adapter_get_handle(size_t index)"
  brief="Get a handle to an adapter."
  detailed="The returned handle must be released with `simpleble_adapter_release_handle`."
  parameters={[{"name":"index","type":"size_t"}]}
/>

<ApiMethod
  signature="void simpleble_adapter_release_handle(simpleble_adapter_t handle)"
  brief="Release an adapter handle."
  parameters={[{"name":"handle","type":"simpleble_adapter_t"}]}
/>

<ApiMethod
  signature="bool simpleble_adapter_is_bluetooth_enabled(void)"
  brief="Check if Bluetooth is enabled on the system."
/>

<ApiMethod
  signature="char* simpleble_adapter_identifier(simpleble_adapter_t handle)"
  brief="Get the adapter identifier."
  detailed="The returned string must be freed with `simpleble_free`."
  parameters={[{"name":"handle","type":"simpleble_adapter_t"}]}
/>

<ApiMethod
  signature="char* simpleble_adapter_address(simpleble_adapter_t handle)"
  brief="Get the adapter MAC address."
  detailed="The returned string must be freed with `simpleble_free`."
  parameters={[{"name":"handle","type":"simpleble_adapter_t"}]}
/>

### Scanning [!toc]

<ApiMethod
  signature="simpleble_err_t simpleble_adapter_scan_start(simpleble_adapter_t handle)"
  brief="Start scanning asynchronously."
  parameters={[{"name":"handle","type":"simpleble_adapter_t"}]}
/>

<ApiMethod
  signature="simpleble_err_t simpleble_adapter_scan_stop(simpleble_adapter_t handle)"
  brief="Stop scanning."
  parameters={[{"name":"handle","type":"simpleble_adapter_t"}]}
/>

<ApiMethod
  signature="simpleble_err_t simpleble_adapter_scan_for(simpleble_adapter_t handle, int timeout_ms)"
  brief="Scan for a specific duration (blocking)."
  parameters={[{"name":"handle","type":"simpleble_adapter_t"},{"name":"timeout_ms","type":"int"}]}
/>

<ApiMethod
  signature="simpleble_err_t simpleble_adapter_scan_is_active(simpleble_adapter_t handle, bool* active)"
  brief="Check if scanning is active."
  parameters={[{"name":"handle","type":"simpleble_adapter_t"},{"name":"active","type":"bool*"}]}
/>

<ApiMethod
  signature="size_t simpleble_adapter_scan_get_results_count(simpleble_adapter_t handle)"
  brief="Get the number of scan results."
  parameters={[{"name":"handle","type":"simpleble_adapter_t"}]}
/>

<ApiMethod
  signature="simpleble_peripheral_t simpleble_adapter_scan_get_results_handle(simpleble_adapter_t handle, size_t index)"
  brief="Get a handle to a found peripheral."
  detailed="The returned handle must be released with `simpleble_peripheral_release_handle`."
  parameters={[{"name":"handle","type":"simpleble_adapter_t"},{"name":"index","type":"size_t"}]}
/>

### Callbacks [!toc]

<ApiMethod
  signature="simpleble_err_t simpleble_adapter_set_callback_on_scan_start(simpleble_adapter_t handle, void (*callback)(simpleble_adapter_t adapter, void* userdata), void* userdata)"
  brief="Set callback for scan start."
/>

<ApiMethod
  signature="simpleble_err_t simpleble_adapter_set_callback_on_scan_stop(simpleble_adapter_t handle, void (*callback)(simpleble_adapter_t adapter, void* userdata), void* userdata)"
  brief="Set callback for scan stop."
/>

<ApiMethod
  signature="simpleble_err_t 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)"
  brief="Set callback for peripheral found."
/>

<ApiMethod
  signature="simpleble_err_t 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)"
  brief="Set callback for peripheral updated."
/>

</ApiClass>

</ApiSection>

<ApiSection title="Peripheral" id="peripheral">

## simpleble_peripheral_t [#simpleble_peripheral_t] [toc]

<ApiClass name="simpleble_peripheral_t" detailed="Handle representing a remote Bluetooth device. You must release this handle using `simpleble_peripheral_release_handle` when done.">

### Lifecycle and Info [!toc]

<ApiMethod
  signature="void simpleble_peripheral_release_handle(simpleble_peripheral_t handle)"
  brief="Release a peripheral handle."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"}]}
/>

<ApiMethod
  signature="char* simpleble_peripheral_identifier(simpleble_peripheral_t handle)"
  brief="Get the peripheral identifier."
  detailed="The returned string must be freed with `simpleble_free`."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"}]}
/>

<ApiMethod
  signature="char* simpleble_peripheral_address(simpleble_peripheral_t handle)"
  brief="Get the peripheral MAC address."
  detailed="The returned string must be freed with `simpleble_free`."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"}]}
/>

<ApiMethod
  signature="int16_t simpleble_peripheral_rssi(simpleble_peripheral_t handle)"
  brief="Get the RSSI value."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"}]}
/>

### Connection [!toc]

<ApiMethod
  signature="simpleble_err_t simpleble_peripheral_connect(simpleble_peripheral_t handle)"
  brief="Connect to the peripheral."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"}]}
/>

<ApiMethod
  signature="simpleble_err_t simpleble_peripheral_disconnect(simpleble_peripheral_t handle)"
  brief="Disconnect from the peripheral."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"}]}
/>

<ApiMethod
  signature="simpleble_err_t simpleble_peripheral_is_connected(simpleble_peripheral_t handle, bool* connected)"
  brief="Check if connected."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"},{"name":"connected","type":"bool*"}]}
/>

<ApiMethod
  signature="simpleble_err_t simpleble_peripheral_is_connectable(simpleble_peripheral_t handle, bool* connectable)"
  brief="Check if connectable."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"},{"name":"connectable","type":"bool*"}]}
/>

### Services and Data [!toc]

<ApiMethod
  signature="size_t simpleble_peripheral_services_count(simpleble_peripheral_t handle)"
  brief="Get the number of services."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"}]}
/>

<ApiMethod
  signature="simpleble_err_t simpleble_peripheral_services_get(simpleble_peripheral_t handle, size_t index, simpleble_service_t* service)"
  brief="Get a service structure."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"},{"name":"index","type":"size_t"},{"name":"service","type":"simpleble_service_t*"}]}
/>

<ApiMethod
  signature="size_t simpleble_peripheral_manufacturer_data_count(simpleble_peripheral_t handle)"
  brief="Get the count of manufacturer data fields."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"}]}
/>

<ApiMethod
  signature="simpleble_err_t simpleble_peripheral_manufacturer_data_get(simpleble_peripheral_t handle, size_t index, simpleble_manufacturer_data_t* manufacturer_data)"
  brief="Get manufacturer data."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"},{"name":"index","type":"size_t"},{"name":"manufacturer_data","type":"simpleble_manufacturer_data_t*"}]}
/>

### GATT Operations [!toc]

<ApiMethod
  signature="simpleble_err_t simpleble_peripheral_read(simpleble_peripheral_t handle, char* service, char* characteristic, uint8_t** data, size_t* data_length)"
  brief="Read a characteristic."
  detailed="The returned data buffer must be freed with `simpleble_free`."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"},{"name":"service","type":"char*"},{"name":"characteristic","type":"char*"},{"name":"data","type":"uint8_t**"},{"name":"data_length","type":"size_t*"}]}
/>

<ApiMethod
  signature="simpleble_err_t simpleble_peripheral_write_request(simpleble_peripheral_t handle, char* service, char* characteristic, uint8_t* data, size_t data_length)"
  brief="Write request (expecting response)."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"},{"name":"service","type":"char*"},{"name":"characteristic","type":"char*"},{"name":"data","type":"uint8_t*"},{"name":"data_length","type":"size_t"}]}
/>

<ApiMethod
  signature="simpleble_err_t simpleble_peripheral_write_command(simpleble_peripheral_t handle, char* service, char* characteristic, uint8_t* data, size_t data_length)"
  brief="Write command (no response)."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"},{"name":"service","type":"char*"},{"name":"characteristic","type":"char*"},{"name":"data","type":"uint8_t*"},{"name":"data_length","type":"size_t"}]}
/>

<ApiMethod
  signature="simpleble_err_t simpleble_peripheral_notify(simpleble_peripheral_t handle, char* service, char* characteristic, void (*callback)(simpleble_uuid_t service, simpleble_uuid_t characteristic, uint8_t* data, size_t data_length, void* userdata), void* userdata)"
  brief="Register for notifications."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"},{"name":"service","type":"char*"},{"name":"characteristic","type":"char*"},{"name":"callback","type":"function"},{"name":"userdata","type":"void*"}]}
/>

<ApiMethod
  signature="simpleble_err_t simpleble_peripheral_indicate(simpleble_peripheral_t handle, char* service, char* characteristic, void (*callback)(simpleble_uuid_t service, simpleble_uuid_t characteristic, uint8_t* data, size_t data_length, void* userdata), void* userdata)"
  brief="Register for indications."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"},{"name":"service","type":"char*"},{"name":"characteristic","type":"char*"},{"name":"callback","type":"function"},{"name":"userdata","type":"void*"}]}
/>

<ApiMethod
  signature="simpleble_err_t simpleble_peripheral_unsubscribe(simpleble_peripheral_t handle, char* service, char* characteristic)"
  brief="Unsubscribe from notifications/indications."
  parameters={[{"name":"handle","type":"simpleble_peripheral_t"},{"name":"service","type":"char*"},{"name":"characteristic","type":"char*"}]}
/>

</ApiClass>

</ApiSection>