hfp: rename create service, document functions

src/hfp.c

@@ -265,7 +265,7 @@ hfp_connection_t * provide_hfp_connection_context_for_bd_addr(bd_addr_t bd_addr)
  */
 
 
-void hfp_create_service(uint8_t * service, uint16_t service_uuid, int rfcomm_channel_nr, const char * name, uint16_t supported_features){
+void hfp_create_sdp_record(uint8_t * service, uint16_t service_uuid, int rfcomm_channel_nr, const char * name, uint16_t supported_features){
     uint8_t* attribute;
     de_create_sequence(service);
 

src/hfp.h

@@ -224,7 +224,7 @@ int get_bit(uint16_t bitmap, int position);
 int store_bit(uint32_t bitmap, int position, uint8_t value);
 // UTILS_END
 
-void hfp_create_service(uint8_t * service, uint16_t service_uuid, int rfcomm_channel_nr, const char * name, uint16_t supported_features);
+void hfp_create_sdp_record(uint8_t * service, uint16_t service_uuid, int rfcomm_channel_nr, const char * name, uint16_t supported_features);
 void hfp_handle_hci_event(hfp_callback_t callback, uint8_t packet_type, uint8_t *packet, uint16_t size);
 void hfp_emit_event(hfp_callback_t callback, uint8_t event_subtype, uint8_t value);
 hfp_connection_t * get_hfp_connection_context_for_rfcomm_cid(uint16_t cid);

src/hfp_ag.c

@@ -106,11 +106,11 @@ static int has_hf_indicators_feature(hfp_connection_t * connection){
     return hf && ag;
 }
 
-void hfp_ag_create_service(uint8_t * service, int rfcomm_channel_nr, const char * name, uint8_t ability_to_reject_call, uint16_t supported_features){
+void hfp_ag_create_sdp_record(uint8_t * service, int rfcomm_channel_nr, const char * name, uint8_t ability_to_reject_call, uint16_t supported_features){
     if (!name){
         name = default_hfp_ag_service_name;
     }
-    hfp_create_service(service, SDP_HandsfreeAudioGateway, rfcomm_channel_nr, name, supported_features);
+    hfp_create_sdp_record(service, SDP_HandsfreeAudioGateway, rfcomm_channel_nr, name, supported_features);
     
     // Network
     de_add_number(service, DE_UINT, DE_SIZE_8, ability_to_reject_call);
@@ -500,6 +500,7 @@ void hfp_ag_establish_service_level_connection(bd_addr_t bd_addr){
     hfp_establish_service_level_connection(bd_addr, SDP_Handsfree);
 }
 
+// TODO trigger release audio connection
 void hfp_ag_release_service_level_connection(bd_addr_t bd_addr){
     hfp_connection_t * connection = hfp_release_service_level_connection(bd_addr);
     hfp_run_for_context(connection);

src/hfp_ag.h

@@ -53,18 +53,46 @@
 extern "C" {
 #endif
 
-void hfp_ag_create_service(uint8_t * service, int rfcomm_channel_nr, const char * name, uint8_t ability_to_reject_call, uint16_t supported_features);;
+/* API_START */
+
+/**
+ * @brief Create HFP Audio Gateway (AG) SDP service record. 
+ */
+void hfp_ag_create_sdp_record(uint8_t * service, int rfcomm_channel_nr, const char * name, uint8_t ability_to_reject_call, uint16_t supported_features);;
+
+/**
+ * @brief Intialize HFP Audio Gateway (AG) device. 
+ * TODO:  move optional params into setters
+ */
 void hfp_ag_init(uint16_t rfcomm_channel_nr, uint32_t supported_features, 
     uint8_t * codecs, int codecs_nr, 
     hfp_ag_indicator_t * ag_indicators, int ag_indicators_nr,
     hfp_hf_indicator_t * hf_indicators, int hf_indicators_nr,
     char *call_hold_services[], int call_hold_services_nr);
+
+/**
+ * @brief Register callback for the HFP Audio Gateway (AG) client. 
+ */
 void hfp_ag_register_packet_handler(hfp_callback_t callback);
 
+/**
+ * @brief Establish RFCOMM connection, and perform service level connection agreement:
+ * - exchange of supported features
+ * - report Audio Gateway (AG) indicators and their status 
+ * - enable indicator status update in the AG
+ * - accept the information about available codecs in the Hands-Free (HF), if sent
+ * - report own information describing the call hold and multiparty services, if possible
+ * - report which HF indicators are enabled on the AG, if possible
+ */
 void hfp_ag_establish_service_level_connection(bd_addr_t bd_addr);
+
+/**
+ * @brief Release the RFCOMM channel and the audio connection between the HF and the AG. 
+ * TODO: trigger release of the audio connection
+ */
 void hfp_ag_release_service_level_connection(bd_addr_t bd_addr);
 
-void hfp_ag_supported_features_exchange(uint16_t supported_features);
+/* API_END */
 
 #if defined __cplusplus
 }

src/hfp_hf.c

@@ -104,11 +104,11 @@ static int has_hf_indicators_feature(hfp_connection_t * connection){
 
 static void packet_handler(void * connection, uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size);
 
-void hfp_hf_create_service(uint8_t * service, int rfcomm_channel_nr, const char * name, uint16_t supported_features){
+void hfp_hf_create_sdp_record(uint8_t * service, int rfcomm_channel_nr, const char * name, uint16_t supported_features){
     if (!name){
         name = default_hfp_hf_service_name;
     }
-    hfp_create_service(service, SDP_Handsfree, rfcomm_channel_nr, name, supported_features);
+    hfp_create_sdp_record(service, SDP_Handsfree, rfcomm_channel_nr, name, supported_features);
 }
 
 
@@ -423,4 +423,24 @@ void hfp_hf_establish_service_level_connection(bd_addr_t bd_addr){
 void hfp_hf_release_service_level_connection(bd_addr_t bd_addr){
     hfp_connection_t * connection = hfp_release_service_level_connection(bd_addr);
     hfp_run_for_context(connection);
-}
+}
+
+void hfp_hf_transfer_registration_status(bd_addr_t bd_addr){
+    
+}
+
+void hfp_hf_activate_ag_indicator(bd_addr_t bd_addr){
+    
+}
+
+void hfp_hf_transfer_signal_strength_indication(bd_addr_t bd_addr){
+
+}
+
+void hfp_hf_transfer_roaming_status_indication(bd_addr_t bd_addr){
+
+}
+
+void hfp_hf_transfer_battery_level_indication_of_ag(bd_addr_t bd_addr){
+
+}

src/hfp_hf.h

@@ -53,13 +53,70 @@
 extern "C" {
 #endif
 
-void hfp_hf_create_service(uint8_t * service, int rfcomm_channel_nr, const char * name, uint16_t supported_features);
+/* API_START */
+
+
+/**
+ * @brief Create HFP Hands-Free (HF) SDP service record. 
+ */
+void hfp_hf_create_sdp_record(uint8_t * service, int rfcomm_channel_nr, const char * name, uint16_t supported_features);
+
+/**
+ * @brief Intialize HFP Hands-Free (HF) device. 
+ * TODO:  move optional params into setters
+ */
 void hfp_hf_init(uint16_t rfcomm_channel_nr, uint32_t supported_features, uint8_t * codecs, int codecs_nr, uint16_t * indicators, int indicators_nr, uint32_t indicators_status);
+
+/**
+ * @brief Register callback for the HFP Hands-Free (HF) client. 
+ */
 void hfp_hf_register_packet_handler(hfp_callback_t callback);
 
+/**
+ * @brief Establish RFCOMM connection, and perform service level connection agreement:
+ * - exchange of supported features
+ * - retrieve Audio Gateway (AG) indicators and their status 
+ * - enable indicator status update in the AG
+ * - notify the AG about its own available codecs, if possible
+ * - retrieve the AG information describing the call hold and multiparty services, if possible
+ * - retrieve which HF indicators are enabled on the AG, if possible
+ */
 void hfp_hf_establish_service_level_connection(bd_addr_t bd_addr);
+
+
+/**
+ * @brief Release the RFCOMM channel and the audio connection between the HF and the AG. 
+ * TODO: trigger release of the audio connection
+ */
 void hfp_hf_release_service_level_connection(bd_addr_t bd_addr);
 
+/**
+ * @brief Enable registration status update in the AG.
+ */
+void hfp_hf_transfer_registration_status(bd_addr_t bd_addr);
+
+/**
+ * @brief Deactivate/reactivate individual indicators in the AG.
+ */
+void hfp_hf_activate_ag_indicator(bd_addr_t bd_addr);
+
+
+/**
+ * @brief
+ */
+void hfp_hf_transfer_signal_strength_indication(bd_addr_t bd_addr);
+
+/**
+ * @brief
+ */
+void hfp_hf_transfer_roaming_status_indication(bd_addr_t bd_addr);
+
+/**
+ * @brief
+ */
+ void hfp_hf_transfer_battery_level_indication_of_ag(bd_addr_t bd_addr);
+
+/* API_END */
 
 #if defined __cplusplus
 }

test/pts/hfp_ag_test.c

@@ -175,7 +175,7 @@ int btstack_main(int argc, const char * argv[]){
     sdp_init();
     // init SDP, create record for SPP and register with SDP
     memset((uint8_t *)hfp_service_buffer, 0, sizeof(hfp_service_buffer));
-    hfp_ag_create_service((uint8_t *)hfp_service_buffer, rfcomm_channel_nr, hfp_ag_service_name, 0, 0);
+    hfp_ag_create_sdp_record((uint8_t *)hfp_service_buffer, rfcomm_channel_nr, hfp_ag_service_name, 0, 0);
 
     sdp_register_service_internal(NULL, (uint8_t *)hfp_service_buffer);
 

test/pts/hfp_hf_test.c

@@ -157,7 +157,7 @@ int btstack_main(int argc, const char * argv[]){
     sdp_init();
     // init SDP, create record for SPP and register with SDP
     memset((uint8_t *)hfp_service_buffer, 0, sizeof(hfp_service_buffer));
-    hfp_hf_create_service((uint8_t *)hfp_service_buffer, rfcomm_channel_nr, hfp_hf_service_name, 0);
+    hfp_hf_create_sdp_record((uint8_t *)hfp_service_buffer, rfcomm_channel_nr, hfp_hf_service_name, 0);
     sdp_register_service_internal(NULL, (uint8_t *)hfp_service_buffer);
 
     // turn on!