From 090e1a2d61d747cde3dab67fe92e1d4deba48eb4 Mon Sep 17 00:00:00 2001 From: Th3maz1ng Date: Mon, 10 Apr 2023 21:23:02 +0200 Subject: [PATCH] Added the API function doc comments --- src/gadget_bridge_parser/gadget_bridge.h | 106 ++++++++++++++++++++++- 1 file changed, 104 insertions(+), 2 deletions(-) diff --git a/src/gadget_bridge_parser/gadget_bridge.h b/src/gadget_bridge_parser/gadget_bridge.h index 3f9e755..3f445b3 100644 --- a/src/gadget_bridge_parser/gadget_bridge.h +++ b/src/gadget_bridge_parser/gadget_bridge.h @@ -18,14 +18,32 @@ #include /** - * @brief Size of the internal buffer used to store incoming data - * which needs to be parsed. + * @brief GADGET_BRIDGE_PARSER_BUFFER_SIZE allows to set the size of the buffer + * which is internally used by the parser to do it's job. * */ #define GADGET_BRIDGE_PARSER_BUFFER_SIZE (300) + +/** + * @brief GADGET_BRIDGE_PARSER_BUFFER_THRESHOLD permits to set a size threshold used to free up + * some space in the parser's internal buffer when the threshold is reached. + * This ensures that we can keep on feeding new data and not get stuck. + * + */ #define GADGET_BRIDGE_PARSER_BUFFER_THRESHOLD (100) +/** + * @brief GADGET_BRIDGE_PARSER_MAX_BODY_SIZE defines the max body size that will be saved in the event_data + * structure when parsing the body of a notification. + * + */ #define GADGET_BRIDGE_PARSER_MAX_BODY_SIZE (200) + +/** + * @brief GADGET_BRIDGE_PARSER_MAX_TITLE_SIZE defines the max title size that will be saved in the event_data + * structure when parsing the title of a notification. + * + */ #define GADGET_BRIDGE_PARSER_MAX_TITLE_SIZE (100) typedef enum gadget_bridge_toast_type @@ -183,28 +201,112 @@ typedef struct gadget_bridge_event_data typedef void (*parser_event_callback_t)(const gadget_bridge_event_data_t *gadget_bridge_event_data); +/** + * @brief Sends an Android toast to GadgetBridge to be displayed on the phone. + * + * @param toast_type the type of the toast (INFO, WARN or ERROR). + * @param message a string representing the message to display. + * @return true if the command was successfully sent. + * @return false otherwise. + */ bool gadget_bridge_send_toast(gadget_bridge_toast_type_e toast_type, const char *message); +/** + * @brief Sends up to two firmwares version to GadgetBridge. + * These are displayed in the display details section of the watch in GadgetBridge. + * + * @param fw1 a string representing the first firmware version. + * @param fw2 a string representing the second firmware version. + * @return true if the command was successfully sent. + * @return false otherwise. + */ bool gadget_bridge_send_firmware_version(const char *fw1, const char *fw2); +/** + * @brief Sends the current battery status to GadgetBridge. + * + * @param battery_level_in_percent the current battery level from 0 to 100%. + * @param battery_level_in_V the current battery voltage in volts (3.942 for example). + * @param is_charging a boolean which indicates if the battery is currently charging or not. + * @return true if the command was successfully sent. + * @return false otherwise. + */ bool gadget_bridge_send_battery_status(uint8_t battery_level_in_percent, float battery_level_in_V, bool is_charging); +/** + * @brief Sends the find phone command to GagdetBridge, this will make the phone ring and vibrate + * so that you can locate it. + * + * @param find_phone a boolean which indicates to make the phone rind and vibrate or not. + * @return true if the command was successfully sent. + * @return false otherwise. + */ bool gadget_bridge_send_find_phone(bool find_phone); +/** + * @brief Sends a command to control the music playback of the phone through GadgetBridge. + * + * @param music_control an enumeration value indicating the action to perform: + * PLAY, PAUSE, NEXT, PREVIOUS, VOLUMEUP etc.. + * @return true if the command was successfully sent. + * @return false otherwise. + */ bool gadget_bridge_send_music_control(gadget_bridge_music_control_e music_control); bool gadget_bridge_handle_call(gadget_bridge_call_action_e call_action); bool gadget_bridge_handle_notification(gadget_bridge_call_action_e notification_action, uint32_t handle, const char *phone_number, const char *message); +/** + * @brief Sends the provided activity data to GadgetBridge. This will then be displayed + * on the app in the activity section. + * + * @param heart_rate_in_bpm the current heart rate in beat per minute + * @param step_count the number of new steps since the last time the count was sent. + * @return true if the command was successfully sent. + * @return false otherwise. + */ bool gadget_bridge_send_activity_data(uint16_t heart_rate_in_bpm, uint32_t step_count); +/** + * @brief Tells GadgetBridge to perform an HTTP request for us. + * @note THIS DOES NOT WORK as GadgetBridge don't and will never have network permission... what a pitty ! + * + * @param id an unsigned integer representing the ID of the http request + * @param url a string representing the URL to fetch + * @param http_request_method a enumeration value specifying the http verb to use : GET, POST, PATCH etc.. + * @param http_body the body to include in the request (not implemented yet) + * @param http_headers various headers to include in the request (not implemented yet) + * @return true if the request has been successfully sent to GadgetBridge + * @return false otherwise + */ bool gadget_bridge_send_http_request(uint32_t id, const char *url, gadget_bridge_http_request_method_e http_request_method, const char *http_body, const http_header_t *http_headers); +//bool gadget_bridge_send_force_calendar_sync(void); + +/** + * @brief Registers a callback function used to listen for GadgetBridge events. + * + * @param parser_event_callback + */ void gadget_bridge_parser_register_event_callback(parser_event_callback_t parser_event_callback); +/** + * @brief Feeds new data to the GadgetBridge parser. + * + * @param data the new chunk of data to parse, it will be copied to the parser's internal buffer, + * so you can free the memory containing the string after calling the function. + * @param length the length in bytes of the new chunk. + * @return gadget_bridge_parser_code_e GADGET_BRIDGE_PARSER_CODE_OK if no error occured. + */ gadget_bridge_parser_code_e gadget_bridge_parser_feed(const char *data, uint16_t length); +/** + * @brief Call this function to run the parser. + * It should be safe to call if in a loop like : while((code = gadget_bridge_parser_run()) == GADGET_BRIDGE_PARSER_CODE_PARSING); + * + * @return gadget_bridge_parser_code_e the parser's execution status code. + */ gadget_bridge_parser_code_e gadget_bridge_parser_run(void); const char *gadget_bridge_parser_code_2_str(gadget_bridge_parser_code_e parser_code);