diff --git a/include/common.h b/include/common.h index d303705..3ae97a6 100644 --- a/include/common.h +++ b/include/common.h @@ -5,7 +5,7 @@ #include /** - * A structure used to get curl response + * @brief A structure used to get curl response. */ struct memory_buffer { char *data; @@ -13,43 +13,43 @@ struct memory_buffer { }; /** - * A structure to represent bot object + * @brief A structure to represent bot object. */ struct tgbot_t { - char token[128]; /**< Bot token */ - char api[512]; /**< Bot API url */ - int32_t offset; /**< Bot offset */ - CURL *curl; /**< Curl object, used to send http requests */ + char token[128]; /**< Bot token. */ + char api[512]; /**< Bot API url. */ + int32_t offset; /**< Bot offset. */ + CURL *curl; /**< Curl object, used to send http requests. */ }; typedef struct tgbot_t tgbot; /** - * A structure to represent Bot information got from getMe API + * @brief A structure to represent Bot information got from getMe API. */ struct tgbot_me_t { - char first_name[256]; - char username[32]; + char first_name[256]; /**< Bot's first name. */ + char username[32]; /**< Bot's username. */ }; typedef struct tgbot_me_t tgbot_me; /** - * A structure to represent Update object + * @brief A structure to represent Update object. */ struct tgbot_update_t { - int64_t update_id; /**< Update id */ - long message_id; /**< Message id */ - int64_t chat_id; /**< Chat id */ - char chat_first_name[256]; /**< Chat first name */ - char chat_last_name[256]; /**< Chat last name */ - char chat_username[32]; /**< Chat username */ - char chat_type[32]; /**< Chat type (private/public) */ - int32_t date; /**< Date in unix timestamp */ - char text[4096]; /**< Message text */ + int64_t update_id; /**< Update id. */ + long message_id; /**< Message id. */ + int64_t chat_id; /**< Chat id. */ + char chat_first_name[256]; /**< Chat first name. */ + char chat_last_name[256]; /**< Chat last name. */ + char chat_username[32]; /**< Chat username. */ + char chat_type[32]; /**< Chat type (private/public). */ + int32_t date; /**< Date in unix timestamp. */ + char text[4096]; /**< Message text. */ }; typedef struct tgbot_update_t tgbot_update; /** - * A structure to represent CallbackQuery object + * @brief A structure to represent CallbackQuery object. */ struct tgbot_cbquery_t { int64_t update_id; @@ -59,17 +59,17 @@ struct tgbot_cbquery_t { int32_t date; char text[4096]; char chat_instance[128]; - char data[64]; /**> Callback data */ + char data[64]; /**> Callback data. */ }; typedef struct tgbot_cbquery_t tgbot_cbquery; /** - * Callback function pointer + * @brief Callback function pointer. */ typedef void (*Callback)(tgbot *bot, tgbot_cbquery *query); /** - * A structure to represent error codes + * @brief A structure to represent error codes. */ enum tgbot_rc { TGBOT_OK = 0, diff --git a/include/tgbot.h b/include/tgbot.h index eb35650..2bcb630 100644 --- a/include/tgbot.h +++ b/include/tgbot.h @@ -6,15 +6,19 @@ #include "types.h" /** - * Initializes the Bot object - * @param[out] bot The Bot object - * @param[in] token The Bot token (obtained from @BotFather) + * @brief Initializes the Bot object. + * + * @param[out] bot The Bot object. + * @param[in] token The Bot token (obtained from @BotFather). + * + * @return TGBOT_OK on success. */ tgbot_rc tgbot_init(tgbot *bot, char *token); /** - * Cleans the memory - * @param bot The Bot object + * @brief Cleans the memory. + * + * @param[out] bot The Bot object. */ void tgbot_destroy(tgbot *bot); diff --git a/include/types.h b/include/types.h index fc91020..03081ca 100644 --- a/include/types.h +++ b/include/types.h @@ -4,25 +4,65 @@ #include "common.h" /** - * A structure to represent keyboard's buttons + * @brief Represents a single button on an inline keyboard. */ struct tgbot_inlinekeyboardbutton_t { - char text[200]; /**< If this field is empty the button will be skipped */ - char url[200]; /**< (Optional) URL of the button */ - char callback_data[64]; /**< Callback data */ + char text[200]; /**< Text of the button. If empty, the button is ignored. */ + char url[200]; /**< (Optional) URL to be opened when the button is pressed. */ + char callback_data[64]; /**< (Optional) Data sent to the bot when the button is pressed. */ }; typedef struct tgbot_inlinekeyboardbutton_t tgbot_inlinekeyboardbutton; +/** + * @brief Represents an inline keyboard. + */ struct tgbot_inlinekeyboard_t { - size_t rows; - size_t columns; - struct tgbot_inlinekeyboardbutton_t *buttons; + size_t rows; /**< Number of rows in the keyboard. */ + size_t columns; /**< Number of columns per row. */ + struct tgbot_inlinekeyboardbutton_t *buttons; /**< Array of buttons. */ }; typedef struct tgbot_inlinekeyboard_t tgbot_inlinekeyboard; +/** + * @brief Allocates a new inline keyboard. + * + * @param[in] rows Number of rows in the keyboard. + * @param[in] columns Number of columns in each row. + * + * @return The pointer to the keyboard or NULL on allocation failure. + */ tgbot_inlinekeyboard *tgbot_new_inlinekeyboard(size_t rows, size_t columns); + +/** + * @brief Adds or updates a button at the specified position in the keyboard. + * + * @param[out] keyboard Pointer to the keyboard to modify. + * @param[in] row Row index of the button (starting from 0). + * @param[in] column Column index of the button (starting from 0). + * @param[in] text Display text for the button. + * @param[in] url Optional URL for the button. + * @param[in] callback_data Optional callback data for the button. + * + * @return TGBOT_OK on success. + */ tgbot_rc tgbot_inlinekeyboard_button(tgbot_inlinekeyboard *keyboard, size_t row, size_t column, const char *text, const char *url, const char *callback_data); + +/** + * @brief Returns a pointer to the keyboard's button. + * + * @param[in] keyboard Keyboard. + * @param[in] row Row index of the button. + * @param[in] column Column index of the button. + * + * @return Pointer to the button, or NULL if the position is invalid. + */ tgbot_inlinekeyboardbutton *tgbot_inlinekeyboard_button_at(tgbot_inlinekeyboard *keyboard, size_t row, size_t column); + +/** + * @brief Frees all memory associated with the given inline keyboard. + * + * @param[in,out] keyboard Pointer to the keyboard structure to deallocate. + */ void tgbot_destroy_inlinekeyboard(tgbot_inlinekeyboard *keyboard); #endif