hsp hs api docu

src/hsp_hs.c

@@ -159,7 +159,7 @@ void hsp_hs_enable_custom_indications(int enable){
     hs_support_custom_indications = enable;
 }
 
-int hsp_hs_send_result(char * result){
+int hsp_hs_send_result(const char * result){
     if (!hs_support_custom_indications) return 1;
     return hsp_hs_send_str_over_rfcomm(rfcomm_cid, result);
 }

src/hsp_hs.h

@@ -52,34 +52,94 @@
 extern "C" {
 #endif
 
+/* API_START */
+
+/**
+ * @brief Packet handler for HSP Headset (HS) events. The HSP HS event has type HCI_EVENT_HSP_META with following subtypes:
+ * - HSP_SUBEVENT_ERROR                        
+ * - HSP_SUBEVENT_AUDIO_CONNECTION_COMPLETE    
+ * - HSP_SUBEVENT_AUDIO_DISCONNECTION_COMPLETE 
+ * - HSP_SUBEVENT_RING                         
+ * - HSP_SUBEVENT_MICROPHONE_GAIN_CHANGED      
+ * - HSP_SUBEVENT_SPEAKER_GAIN_CHANGED         
+ * - HSP_SUBEVENT_AG_INDICATION                
+ */
 typedef void (*hsp_hs_callback_t)(uint8_t * event, uint16_t event_size);
 
+/**
+ * @brief Set up HSP HS
+ * @param rfcomm_channel_nr
+ */
 void hsp_hs_init(uint8_t rfcomm_channel_nr);
 
+/**
+ * @brief Create HSP Headset (HS) SDP service record. have_remote_audio_control?
+ */
 void hsp_hs_create_sdp_record(uint8_t * service, int rfcomm_channel_nr, const char * name, uint8_t have_remote_audio_control);
 
-// Register callback (packet handler) for hsp headset
+/**
+ * @brief Register packet handler to receive HSP HS events.
+ */
 void hsp_hs_register_packet_handler(hsp_hs_callback_t callback);
 
+/**
+ * @brief Connect to HSP Audio Gateway
+ *
+ * Perform SDP query for an RFCOMM service on a remote device, 
+ * and establish an RFCOMM connection if such service is found. The reception of the  
+ * HSP_SUBEVENT_AUDIO_CONNECTION_COMPLETE or 
+ * HSP_SUBEVENT_AUDIO_DISCONNECTION_COMPLETE event
+ * indicate if the connection is successfully established or not. 
+ */
 void hsp_hs_connect(bd_addr_t bd_addr);
 
+/**
+ * @brief Disconnect from HSP Audio Gateway
+ *
+ * Releases the RFCOMM channel.
+ */
 void hsp_hs_disconnect(bd_addr_t bd_addr);
 
-// AT+VGM=[0..15]
+/**
+ * @brief Set microphone gain. 
+ * 
+ * The new gain value will be confirmed by the HSP Audio Gateway. 
+ * A HSP_SUBEVENT_MICROPHONE_GAIN_CHANGED event will be received.
+ * @param gain - valid range: [0,15]
+ */
 void hsp_hs_set_microphone_gain(uint8_t gain);
 
-// AT+VGS=[0..15]
+/**
+ * @brief Set speaker gain. 
+ * 
+ * The new gain value will be confirmed by the HSP Audio Gateway. 
+ * A HSP_SUBEVENT_SPEAKER_GAIN_CHANGED event will be received.
+ * @param gain - valid range: [0,15]
+ */
 void hsp_hs_set_speaker_gain(uint8_t gain);
 
+/**
+ * @brief Send button press action. 
+ */
 void hsp_hs_send_button_press(void);
 
-// When support custom indications is enabled, HS will send HSP_SUBEVENT_HS_INDICATION.
+/**
-// On occurance of this event, client's packet handler must send the result back
+ * @brief Enable custom indications
-// by calling hsp_hs_send_result function.
+ * 
-
+ * Custom indications are disable by default. 
+ * When enabled, custom indications are received via the HSP_SUBEVENT_AG_INDICATION.
+ */
 void hsp_hs_enable_custom_indications(int enable);
 
-int hsp_hs_send_result(char * indication);
+/**
+ * @brief Send answer to custom command
+ *
+ * On HSP_SUBEVENT_AG_INDICATION, the client needs to respond
+ * with this function with the result to the custom indication
+ */
+int hsp_hs_send_result(const char * indication);
+
+/* API_END */
 
 #if defined __cplusplus
 }