include: let SoftDevice BLE event handlers be public

Let all SoftDevice event handlers used for BLE event observers
be public, and align their documentation.

Signed-off-by: Emanuele Di Santo <emdi@nordicsemi.no>

Author: lemrey

include/bm/bluetooth/ble_adv.h

@@ -238,12 +238,19 @@ struct ble_adv_config {
 };
 
 /**
- * @brief Library's Bluetooth LE event handler.
+ * @brief Bluetooth LE event handler for the advertising library.
+ *
+ * @details Handles all Bluetooth LE stack events that are of interest to the
+ *          advertising library.
+ *
+ * @note This handler is registered automatically by @ref BLE_ADV_DEF and is
+ *       called by the SoftDevice handler. The application does not need to call
+ *       it directly.
  *
  * @param[in] ble_evt Bluetooth LE stack event.
- * @param[in] ble_adv Advertising Module instance.
+ * @param[in] adv     Pointer to the @ref ble_adv instance.
  */
-void ble_adv_on_ble_evt(const ble_evt_t *ble_evt, void *ble_adv);
+void ble_adv_on_ble_evt(const ble_evt_t *ble_evt, void *adv);
 
 /**
  * @brief Initialize the Bluetooth LE advertising library.

include/bm/bluetooth/ble_db_discovery.h

@@ -241,12 +241,19 @@ uint32_t ble_db_discovery_service_register(struct ble_db_discovery *db_discovery
 					   const ble_uuid_t *uuid);
 
 /**
- * @brief Application's Bluetooth LE Stack event handler.
+ * @brief Bluetooth LE event handler for the Database Discovery library.
  *
- * @param[in] ble_evt Event received.
- * @param[in,out] context DB discovery instance.
+ * @details Handles all Bluetooth LE stack events that are of interest to the
+ *          Database Discovery library.
+ *
+ * @note This handler is registered automatically by @ref BLE_DB_DISCOVERY_DEF and
+ *       is called by the SoftDevice handler. The application does not need to
+ *       call it directly.
+ *
+ * @param[in] ble_evt      Bluetooth LE stack event.
+ * @param[in] db_discovery Pointer to the @ref ble_db_discovery instance.
  */
-void ble_db_discovery_on_ble_evt(const ble_evt_t *ble_evt, void *context);
+void ble_db_discovery_on_ble_evt(const ble_evt_t *ble_evt, void *db_discovery);
 
 #endif /* BLE_DB_DISCOVERY_H__ */
 

include/bm/bluetooth/ble_gq.h

@@ -300,16 +300,19 @@ uint32_t ble_gq_item_add(const struct ble_gq *gatt_queue, struct ble_gq_req *req
 uint32_t ble_gq_conn_handle_register(const struct ble_gq *gatt_queue, uint16_t conn_handle);
 
 /**
- * @brief Handle Bluetooth LE events from the SoftDevice.
+ * @brief Bluetooth LE event handler for the GATT Queue library.
  *
- * @details This function handles the Bluetooth LE events received from the SoftDevice. If an
- *          event is relevant to the BGQ module, it is used to update internal variables,
- *          process queued GATT requests and, if necessary, send errors to the application.
+ * @details Handles all Bluetooth LE stack events that are of interest to the
+ *          GATT Queue library.
  *
- * @param[in] ble_evt     Pointer to the event.
- * @param[in] gatt_queue  Pointer to the @ref ble_gq instance.
+ * @note This handler is registered automatically by @ref BLE_GQ_DEF and is
+ *       called by the SoftDevice handler. The application does not need to call
+ *       it directly.
+ *
+ * @param[in] ble_evt Bluetooth LE stack event.
+ * @param[in] gq      Pointer to the @ref ble_gq instance.
  */
-void ble_gq_on_ble_evt(const ble_evt_t *ble_evt, void *gatt_queue);
+void ble_gq_on_ble_evt(const ble_evt_t *ble_evt, void *gq);
 
 #ifdef __cplusplus
 }

include/bm/bluetooth/ble_qwr.h

@@ -180,15 +180,19 @@ uint32_t ble_qwr_init(struct ble_qwr *qwr, const struct ble_qwr_config *qwr_conf
 uint32_t ble_qwr_conn_handle_assign(struct ble_qwr *qwr, uint16_t conn_handle);
 
 /**
- * @brief Function for handling Bluetooth LE stack events.
+ * @brief Bluetooth LE event handler for the Queued Writes module.
  *
- * @details Handles all events from the Bluetooth LE stack that are of interest to the
+ * @details Handles all Bluetooth LE stack events that are of interest to the
  *          Queued Writes module.
  *
- * @param[in] ble_evt Event received.
- * @param[in] context Queued Writes structure.
+ * @note This handler is registered automatically by @ref BLE_QWR_DEF and is
+ *       called by the SoftDevice handler. The application does not need to call
+ *       it directly.
+ *
+ * @param[in] ble_evt Bluetooth LE stack event.
+ * @param[in] qwr     Pointer to the @ref ble_qwr instance.
  */
-void ble_qwr_on_ble_evt(const ble_evt_t *ble_evt, void *context);
+void ble_qwr_on_ble_evt(const ble_evt_t *ble_evt, void *qwr);
 
 #if (CONFIG_BLE_QWR_MAX_ATTR > 0)
 /**

include/bm/bluetooth/ble_scan.h

@@ -42,7 +42,6 @@ extern "C" {
  */
 #define BLE_SCAN_DEF(_name)                                                                        \
 	static struct ble_scan _name;                                                              \
-	extern void ble_scan_on_ble_evt(const ble_evt_t *ble_evt, void *ctx);                      \
 	NRF_SDH_BLE_OBSERVER(_name##_obs, ble_scan_on_ble_evt, &_name, HIGH)
 
 /**
@@ -565,10 +564,17 @@ uint32_t ble_scan_all_filter_remove(struct ble_scan *scan);
 uint32_t ble_scan_params_set(struct ble_scan *scan, const ble_gap_scan_params_t *scan_params);
 
 /**
- * @brief Handler for Bluetooth LE stack events.
+ * @brief Bluetooth LE event handler for the Scanning library.
  *
- * @param[in] ble_evt Bluetooth LE event.
- * @param[in,out] scan Scan library instance.
+ * @details Handles all Bluetooth LE stack events that are of interest to the
+ *          Scanning library.
+ *
+ * @note This handler is registered automatically by @ref BLE_SCAN_DEF and is
+ *       called by the SoftDevice handler. The application does not need to call
+ *       it directly.
+ *
+ * @param[in] ble_evt Bluetooth LE stack event.
+ * @param[in] scan    Pointer to the @ref ble_scan instance.
  */
 void ble_scan_on_ble_evt(const ble_evt_t *ble_evt, void *scan);
 

include/bm/bluetooth/services/ble_bas.h

@@ -29,7 +29,6 @@ extern "C" {
  */
 #define BLE_BAS_DEF(_name)                                                                         \
 	static struct ble_bas _name;                                                               \
-	extern void ble_bas_on_ble_evt(const ble_evt_t *ble_evt, void *ctx);                       \
 	NRF_SDH_BLE_OBSERVER(_name##_obs, ble_bas_on_ble_evt, &_name, HIGH)
 
 /** @brief Default security configuration. */
@@ -218,6 +217,21 @@ uint32_t ble_bas_init(struct ble_bas *bas, const struct ble_bas_config *bas_conf
 uint32_t ble_bas_battery_level_update(struct ble_bas *bas, uint16_t conn_handle,
 				      uint8_t battery_level);
 
+/**
+ * @brief Bluetooth LE event handler for the Battery Service.
+ *
+ * @details Handles all Bluetooth LE stack events that are of interest to the
+ *          Battery Service.
+ *
+ * @note This handler is registered automatically by @ref BLE_BAS_DEF and is
+ *       called by the SoftDevice handler. The application does not need to call
+ *       it directly.
+ *
+ * @param[in] ble_evt Bluetooth LE stack event.
+ * @param[in] bas     Pointer to the @ref ble_bas instance.
+ */
+void ble_bas_on_ble_evt(const ble_evt_t *ble_evt, void *bas);
+
 #ifdef __cplusplus
 }
 #endif

include/bm/bluetooth/services/ble_bas_client.h

@@ -157,19 +157,19 @@ uint32_t ble_bas_client_init(struct ble_bas_client *bas_client,
 			     const struct ble_bas_client_config *bas_client_config);
 
 /**
- * @brief Handle Bluetooth LE events from the SoftDevice.
+ * @brief Bluetooth LE event handler for the Battery Service Client.
  *
- * @details This function handles the Bluetooth LE events received from the SoftDevice. If a
- *          Bluetooth LE event is relevant to the Battery Service Client module, the function uses
- *          the event's data to update interval variables and, if necessary, send events to the
- *          application.
+ * @details Handles all Bluetooth LE stack events that are of interest to the
+ *          Battery Service Client.
  *
- * @note This function must be called by the application.
+ * @note This handler is registered automatically by @ref BLE_BAS_CLIENT_DEF and
+ *       is called by the SoftDevice handler. The application does not need to
+ *       call it directly.
  *
- * @param[in] ble_evt Bluetooth LE event.
- * @param[in] context Battery Service client structure.
+ * @param[in] ble_evt    Bluetooth LE stack event.
+ * @param[in] bas_client Pointer to the @ref ble_bas_client instance.
  */
-void ble_bas_client_on_ble_evt(const ble_evt_t *ble_evt, void *context);
+void ble_bas_client_on_ble_evt(const ble_evt_t *ble_evt, void *bas_client);
 
 /**
  * @brief Enable notifications on the Battery Level characteristic.

include/bm/bluetooth/services/ble_bms.h

@@ -314,15 +314,19 @@ uint32_t ble_bms_auth_response(struct ble_bms *bms, bool authorize);
 uint32_t ble_bms_init(struct ble_bms *bms, struct ble_bms_config *bms_config);
 
 /**
- * @brief   Handle Bond Management Bluetooth LE stack events.
+ * @brief Bluetooth LE event handler for the Bond Management Service.
  *
- * @details This function handles all events from the Bluetooth LE stack that are of interest to the
+ * @details Handles all Bluetooth LE stack events that are of interest to the
  *          Bond Management Service.
  *
- * @param[in] ble_evt Event received.
- * @param[in] context BMS structure.
+ * @note This handler is registered automatically by @ref BLE_BMS_DEF and is
+ *       called by the SoftDevice handler. The application does not need to call
+ *       it directly.
+ *
+ * @param[in] ble_evt Bluetooth LE stack event.
+ * @param[in] bms     Pointer to the @ref ble_bms instance.
  */
-void ble_bms_on_ble_evt(const ble_evt_t *ble_evt, void *context);
+void ble_bms_on_ble_evt(const ble_evt_t *ble_evt, void *bms);
 
 /**
  * @brief Handle events from the @ref nrf_ble_qwr.

include/bm/bluetooth/services/ble_cgms.h

@@ -590,14 +590,19 @@ struct ble_cgms {
 uint32_t ble_cgms_init(struct ble_cgms *cgms, const struct ble_cgms_config *cgms_init);
 
 /**
- * @brief Function for handling the application's Bluetooth LE stack events.
+ * @brief Bluetooth LE event handler for the Continuous Glucose Monitoring Service.
  *
- * @details Handles all events from the Bluetooth LE stack that are of interest to the CGM Service.
+ * @details Handles all Bluetooth LE stack events that are of interest to the
+ *          Continuous Glucose Monitoring Service.
  *
- * @param[in] ble_evt Event received.
- * @param[in] context Instance of the CGM Service.
+ * @note This handler is registered automatically by @ref BLE_CGMS_DEF and is
+ *       called by the SoftDevice handler. The application does not need to call
+ *       it directly.
+ *
+ * @param[in] ble_evt Bluetooth LE stack event.
+ * @param[in] cgms    Pointer to the @ref ble_cgms instance.
  */
-void ble_cgms_on_ble_evt(const ble_evt_t *ble_evt, void *context);
+void ble_cgms_on_ble_evt(const ble_evt_t *ble_evt, void *cgms);
 
 /**
  * @brief Report a new glucose measurement to the CGM Service module.

include/bm/bluetooth/services/ble_hids.h

@@ -700,17 +700,19 @@ struct ble_hids {
 };
 
 /**
- * @brief Function for handling the Application's Bluetooth LE Stack events.
+ * @brief Bluetooth LE event handler for the HID Service.
  *
- * @details Handles all events from the Bluetooth LE stack of interest to the HID Service.
+ * @details Handles all Bluetooth LE stack events that are of interest to the
+ *          HID Service.
  *
- * @note This function is registered with a NRF_SDH_BLE_OBSERVER and is called automatically
- *       by the SoftDevice Handler.
+ * @note This handler is registered automatically by @ref BLE_HIDS_DEF and is
+ *       called by the SoftDevice handler. The application does not need to call
+ *       it directly.
  *
- * @param[in] ble_evt Event received.
- * @param[in] context HID Service structure.
+ * @param[in] ble_evt Bluetooth LE stack event.
+ * @param[in] hids    Pointer to the @ref ble_hids instance.
  */
-void ble_hids_on_ble_evt(const ble_evt_t *ble_evt, void *context);
+void ble_hids_on_ble_evt(const ble_evt_t *ble_evt, void *hids);
 
 /**
  * @brief Function for initializing the HID Service.