diff --git a/doxygen-awesome-css b/doxygen-awesome-css index 8cea9a073e..00a52f6c74 160000 --- a/doxygen-awesome-css +++ b/doxygen-awesome-css @@ -1 +1 @@ -Subproject commit 8cea9a073ecd50a5b2c0958a3df100292d6c7374 +Subproject commit 00a52f6c74065ffbd836cbd791ddfe8edf2836b8 diff --git a/include/dpp/guild.h b/include/dpp/guild.h index fd6a3d8a98..cbb394ce15 100644 --- a/include/dpp/guild.h +++ b/include/dpp/guild.h @@ -35,125 +35,302 @@ namespace dpp { class channel; +/* Note from Archie: I'd like to move this soon (dpp::guild::region) and allow users to use a region enum. + * This would make it easier for people to be able to alter a channel region without having to get the text right. + */ + /** * @brief Represents voice regions for guilds and channels. * @deprecated Deprecated in favour of per-channel regions. - * Please use channel::rtc_region instead. + * Please use dpp::channel::rtc_region instead. */ enum region : uint8_t { - r_brazil, //!< Brazil - r_central_europe, //!< Central Europe - r_hong_kong, //!< Hong Kong - r_india, //!< India - r_japan, //!< Japan - r_russia, //!< Russia - r_singapore, //!< Singapore - r_south_africa, //!< South Africa - r_sydney, //!< Sydney - r_us_central, //!< US Central - r_us_east, //!< US East Coast - r_us_south, //!< US South - r_us_west, //!< US West Coast - r_western_europe //!< Western Europe + /** + * @brief Brazil + */ + r_brazil, + + /** + * @brief Central Europe + */ + r_central_europe, + + /** + * @brief Hong Kong + */ + r_hong_kong, + + /** + * @brief India + */ + r_india, + + /** + * @brief Japan + */ + r_japan, + + /** + * @brief Russia + */ + r_russia, + + /** + * @brief Singapore + */ + r_singapore, + + /** + * @brief South Africa + */ + r_south_africa, + + /** + * @brief Sydney + */ + r_sydney, + + /** + * @brief US Central + */ + r_us_central, + + /** + * @brief US East Coast + */ + r_us_east, + + /** + * @brief US South + */ + r_us_south, + + /** + * @brief US West Coast + */ + r_us_west, + + /** + * @brief Western Europe + */ + r_western_europe }; /** * @brief The various flags that represent the status of a dpp::guild object */ enum guild_flags : uint32_t { - /** Large guild */ - g_large = 0b00000000000000000000000000000001, - /** Unavailable guild (inaccessible due to an outage) */ - g_unavailable = 0b00000000000000000000000000000010, - /** Guild has widget enabled */ - g_widget_enabled = 0b00000000000000000000000000000100, - /** Guild can have an invite splash image */ - g_invite_splash = 0b00000000000000000000000000001000, - /** Guild can have VIP regions */ - g_vip_regions = 0b00000000000000000000000000010000, - /** Guild can have a vanity url */ - g_vanity_url = 0b00000000000000000000000000100000, - /** Guild is verified */ - g_verified = 0b00000000000000000000000001000000, - /** Guild is partnered */ - g_partnered = 0b00000000000000000000000010000000, - /** Community features enabled */ - g_community = 0b00000000000000000000000100000000, - /** Guild has enabled role subscriptions */ - g_role_subscription_enabled = 0b00000000000000000000001000000000, - /** Guild has access to create announcement channels */ - g_news = 0b00000000000000000000010000000000, - /** Guild is discoverable in discovery */ - g_discoverable = 0b00000000000000000000100000000000, - /** Guild is featureable */ - g_featureable = 0b00000000000000000001000000000000, - /** Guild can have an animated icon (doesn't mean it actually has one though) */ - g_animated_icon = 0b00000000000000000010000000000000, - /** Guild can have a banner image */ - g_banner = 0b00000000000000000100000000000000, - /** Guild has a welcome screen */ - g_welcome_screen_enabled = 0b00000000000000001000000000000000, - /** Guild has a member verification gate */ - g_member_verification_gate = 0b00000000000000010000000000000000, - /** Guild has a preview */ - g_preview_enabled = 0b00000000000000100000000000000000, - /** Guild join notifications are off */ - g_no_join_notifications = 0b00000000000001000000000000000000, - /** Guild boost notifications are off */ - g_no_boost_notifications = 0b00000000000010000000000000000000, - /** Guild has an actual animated icon (set by the icon hash starting with 'a_') */ - g_has_animated_icon = 0b00000000000100000000000000000000, - /** Guild has an actual animated banner (set by the icon hash starting with 'a_') */ - g_has_animated_banner = 0b00000000001000000000000000000000, - /** Guild setup tips are off */ - g_no_setup_tips = 0b00000000010000000000000000000000, - /** "Wave to say hi" sticker prompt buttons are off */ - g_no_sticker_greeting = 0b00000000100000000000000000000000, - /** guild has enabled monetization */ - g_monetization_enabled = 0b00000001000000000000000000000000, - /** guild has increased custom sticker slots */ - g_more_stickers = 0b00000010000000000000000000000000, - /** Guild has enabled the role subscription promo page */ - g_creator_store_page_enabled = 0b00000100000000000000000000000000, - /** guild is able to set role icons */ - g_role_icons = 0b00001000000000000000000000000000, - /** guild has access to the seven day archive time for threads + /** + * @brief Large guild + */ + g_large = 0b00000000000000000000000000000001, + + /** + * @brief Unavailable guild (inaccessible due to an outage) + */ + g_unavailable = 0b00000000000000000000000000000010, + + /** + * @brief Guild has widget enabled + */ + g_widget_enabled = 0b00000000000000000000000000000100, + + /** + * @brief Guild can have an invite splash image + */ + g_invite_splash = 0b00000000000000000000000000001000, + + /** + * @brief Guild can have VIP regions + */ + g_vip_regions = 0b00000000000000000000000000010000, + + /** + * @brief Guild can have a vanity url + */ + g_vanity_url = 0b00000000000000000000000000100000, + + /** + * @brief Guild is verified + */ + g_verified = 0b00000000000000000000000001000000, + + /** + * @brief Guild is partnered + */ + g_partnered = 0b00000000000000000000000010000000, + + /** + * @brief Community features enabled + */ + g_community = 0b00000000000000000000000100000000, + + /** + * @brief Guild has enabled role subscriptions + */ + g_role_subscription_enabled = 0b00000000000000000000001000000000, + + /** + * @brief Guild has access to create announcement channels + */ + g_news = 0b00000000000000000000010000000000, + + /** + * @brief Guild is discoverable in discovery + */ + g_discoverable = 0b00000000000000000000100000000000, + + /** + * @brief Guild is featureable + */ + g_featureable = 0b00000000000000000001000000000000, + + /** + * @brief Guild can have an animated icon (doesn't mean it actually has one though) + */ + g_animated_icon = 0b00000000000000000010000000000000, + + /** + * @brief Guild can have a banner image + */ + g_banner = 0b00000000000000000100000000000000, + + /** + * @brief Guild has a welcome screen + */ + g_welcome_screen_enabled = 0b00000000000000001000000000000000, + + /** + * @brief Guild has a member verification gate + */ + g_member_verification_gate = 0b00000000000000010000000000000000, + + /** + * @brief Guild has a preview + */ + g_preview_enabled = 0b00000000000000100000000000000000, + + /** + * @brief Guild join notifications are off + */ + g_no_join_notifications = 0b00000000000001000000000000000000, + + /** + * @brief Guild boost notifications are off + */ + g_no_boost_notifications = 0b00000000000010000000000000000000, + + /** + * @brief Guild has an actual animated icon (set by the icon hash starting with 'a_') + */ + g_has_animated_icon = 0b00000000000100000000000000000000, + + /** + * @brief Guild has an actual animated banner (set by the icon hash starting with 'a_') + */ + g_has_animated_banner = 0b00000000001000000000000000000000, + + /** + * @brief Guild setup tips are off + */ + g_no_setup_tips = 0b00000000010000000000000000000000, + + /** + * @brief "Wave to say hi" sticker prompt buttons are off + */ + g_no_sticker_greeting = 0b00000000100000000000000000000000, + + /** + * @brief Guild has enabled monetization + */ + g_monetization_enabled = 0b00000001000000000000000000000000, + + /** + * @brief Guild has increased custom sticker slots + */ + g_more_stickers = 0b00000010000000000000000000000000, + + /** + * @brief Guild has enabled the role subscription promo page + */ + g_creator_store_page_enabled = 0b00000100000000000000000000000000, + + /** + * @brief Guild is able to set role icons + */ + g_role_icons = 0b00001000000000000000000000000000, + + /** + * @brief Guild has access to the seven day archive time for threads * @deprecated Removed by Discord */ - g_seven_day_thread_archive = 0b00010000000000000000000000000000, - /** guild has access to the three day archive time for threads + g_seven_day_thread_archive = 0b00010000000000000000000000000000, + + /** + * @brief Guild has access to the three day archive time for threads * @deprecated Removed by Discord */ - g_three_day_thread_archive = 0b00100000000000000000000000000000, - /** guild has enabled ticketed events */ - g_ticketed_events = 0b01000000000000000000000000000000, - /** guild can have channel banners + g_three_day_thread_archive = 0b00100000000000000000000000000000, + + /** + * @brief Guild has enabled ticketed events + */ + g_ticketed_events = 0b01000000000000000000000000000000, + + /** + * @brief Guild can have channel banners * @deprecated Removed by Discord */ - g_channel_banners = 0b10000000000000000000000000000000, + g_channel_banners = 0b10000000000000000000000000000000, }; /** * @brief Additional boolean flag values for guild, as guild_flags is full */ enum guild_flags_extra : uint16_t { - /** Guild has premium progress bar enabled */ - g_premium_progress_bar_enabled = 0b0000000000000001, - /** Guild can have an animated banner (doesn't mean it actually has one though) */ - g_animated_banner = 0b0000000000000010, - /** Guild has auto moderation */ - g_auto_moderation = 0b0000000000000100, - /** Guild has paused invites, preventing new users from joining */ - g_invites_disabled = 0b0000000000001000, - /** Guild has been set as support server of an app in the App Directory */ - g_developer_support_server = 0b0000000000010000, - /** Guild role subscription purchase and renewal notifications are off */ + /** + * @brief Guild has premium progress bar enabled + */ + g_premium_progress_bar_enabled = 0b0000000000000001, + + /** + * @brief Guild can have an animated banner (doesn't mean it actually has one though) + */ + g_animated_banner = 0b0000000000000010, + + /** + * @brief Guild has auto moderation + */ + g_auto_moderation = 0b0000000000000100, + + /** + * @brief Guild has paused invites, preventing new users from joining + */ + g_invites_disabled = 0b0000000000001000, + + /** + * @brief Guild has been set as support server of an app in the App Directory + */ + g_developer_support_server = 0b0000000000010000, + + /** + * @brief Guild role subscription purchase and renewal notifications are off + */ g_no_role_subscription_notifications = 0b0000000000100000, - /** Guild role subscription sticker reply buttons are off */ + + /** + * @brief Guild role subscription sticker reply buttons are off + */ g_no_role_subscription_notification_replies = 0b0000000001000000, - /** Guild has role subscriptions that can be purchased */ + + /** + * @brief Guild has role subscriptions that can be purchased + */ g_role_subscriptions_available_for_purchase = 0b0000000010000000, - /** Guild has disabled alerts for join raids in the configured safety alerts channel */ + + /** + * @brief Guild has disabled alerts for join raids in the configured safety alerts channel + */ g_raid_alerts_disabled = 0b0000000100000000, }; @@ -162,25 +339,63 @@ enum guild_flags_extra : uint16_t { * @note Use the setter functions in dpp::guild_member and do not toggle the bits yourself. */ enum guild_member_flags : uint16_t { - /** Member deafened in voice channels */ - gm_deaf = 0b0000000000000001, - /** Member muted in voice channels */ - gm_mute = 0b0000000000000010, - /** Member pending verification by membership screening */ - gm_pending = 0b0000000000000100, - /** Member has animated guild-specific avatar */ - gm_animated_avatar = 0b0000000000001000, - /** gm_deaf or gm_mute has been toggled */ - gm_voice_action = 0b0000000000010000, - /** Member has left and rejoined the guild */ + /** + * @brief Member deafened in voice channel + */ + gm_deaf = 0b0000000000000001, + + /** + * @brief Member muted in voice channels + */ + gm_mute = 0b0000000000000010, + + /** + * @brief Member pending verification by membership screening + */ + gm_pending = 0b0000000000000100, + + /** + * @brief Member has animated guild-specific avatar + */ + gm_animated_avatar = 0b0000000000001000, + + /** + * @brief gm_deaf or gm_mute has been toggled + */ + gm_voice_action = 0b0000000000010000, + + /** + * @brief Member has left and rejoined the guild + */ gm_did_rejoin = 0b0000000000100000, - /** Member has completed onboarding */ + + /** + * @brief Member has completed onboarding + */ gm_completed_onboarding = 0b0000000001000000, - /** Member is exempt from guild verification requirements */ + + /** + * @brief Member is exempt from guild verification requirements + */ gm_bypasses_verification = 0b0000000010000000, - /** Member has started onboarding */ + + /** + * @brief Member has started onboarding + */ gm_started_onboarding = 0b0000000100000000, - gm_roles_action = 0b0000001000000000, + + /** + * @brief Should change roles on next call to edit guild_member? + * @warning This is set by dpp::guild_member::add_role, dpp::guild_member::remove_role, and dpp::guild_member::set_roles. + * You should only ever use this value if you know what you're doing, otherwise stick to the three functions listed. + */ + gm_roles_action = 0b0000001000000000, + + /** + * @brief Should nicknames on next call to edit guild_member? + * @warning This is set by dpp::guild_member::set_nickname. + * You should only ever use this value if you know what you're doing, otherwise stick to the function listed. + */ gm_nickname_action = 0b0000010000000000, }; @@ -201,33 +416,63 @@ class DPP_EXPORT guild_member : public json_interface { json to_json_impl(bool with_id = false) const; protected: - /** Nickname, or empty string if they don't have a nickname on this guild */ + /** + * @brief Nickname. + * + * @note Empty string if they don't have a nickname on this guild + */ std::string nickname; - /** List of roles this user has on this guild */ + + /** + * @brief List of roles this user has on this guild + */ std::vector roles; - /** A set of flags built from the bitmask defined by dpp::guild_member_flags */ + + /** + * @brief A set of flags built from the bitmask defined by dpp::guild_member_flags + */ uint16_t flags; friend void from_json(const nlohmann::json& j, guild_member& gm); public: - /** Guild id */ + /** + * @brief Guild id + */ snowflake guild_id; - /** User id */ + + /** + * @brief User id + */ snowflake user_id; - /** User avatar (per-server avatar is a nitro only feature) */ + + /** + * @brief User avatar. + * + * @note Per-server avatar is a nitro only feature. + */ utility::iconhash avatar; - /** timestamp of when the time out will be removed; until then, they cannot interact with the guild */ + + /** + * @brief Timestamp of when the time out will be removed; until then, they cannot interact with the guild + */ time_t communication_disabled_until; - /** Date and time the user joined the guild */ + + /** + * @brief Date and time the user joined the guild. + */ time_t joined_at; - /** Boosting since */ + + /** + * @brief The Date and time the user started boosting. + */ time_t premium_since; /** Default constructor */ guild_member(); - /** Fill this object from a json object. + /** + * @brief Fill this object from a json object. * @param j The json object to get data from * @param g_id The guild id to associate the member with * @param u_id The user id to associate the member with @@ -440,7 +685,7 @@ class DPP_EXPORT guild_member : public json_interface { /** * @brief Defines a channel on a server's welcome screen */ -struct DPP_EXPORT welcome_channel: public json_interface { +struct DPP_EXPORT welcome_channel : public json_interface { protected: friend struct json_interface; @@ -461,13 +706,26 @@ struct DPP_EXPORT welcome_channel: public json_interface { json to_json_impl(bool with_id = false) const; public: - /// The description shown for the channel + /** + * @brief The description shown for the channel. + */ std::string description; - /// The emoji name if custom, the unicode character if standard, or null if no emoji is set + + /** + * @brief The emoji name. + * + * @note name if custom, the unicode character if standard, or null if no emoji is set. + */ std::string emoji_name; - /// The channel's id + + /** + * @brief The channel's id. + */ snowflake channel_id; - /// The emoji id, if the emoji is custom + + /** + * @brief The emoji id, if the emoji is custom. + */ snowflake emoji_id; /** @@ -501,7 +759,7 @@ struct DPP_EXPORT welcome_channel: public json_interface { /** * @brief Defines a server's welcome screen */ -struct DPP_EXPORT welcome_screen: public json_interface { +struct DPP_EXPORT welcome_screen : public json_interface { protected: friend struct json_interface; @@ -522,9 +780,14 @@ struct DPP_EXPORT welcome_screen: public json_interface { json to_json_impl(bool with_id = false) const; public: - /// The server description shown in the welcome screen + /** + * @brief The server description shown in the welcome screen + */ std::string description; - /// The channels shown in the welcome screen (max 5) + + /** + * @brief The channels shown in the welcome screen (max 5) + */ std::vector welcome_channels; /** @@ -552,14 +815,25 @@ struct DPP_EXPORT welcome_screen: public json_interface { * @note This is set by Discord, and cannot be set by any bot or user on the guild. */ enum guild_nsfw_level_t : uint8_t { - /// Default setting, not configured - nsfw_default = 0, - /// Explicit content may be in this guild - nsfw_explicit = 1, - /// Safe for work content only - nsfw_safe = 2, - /// Age restricted, 18+ - nsfw_age_restricted = 3 + /** + * @brief Default setting, not configured + */ + nsfw_default = 0, + + /** + * @brief Explicit content may be in this guild + */ + nsfw_explicit = 1, + + /** + * @brief Safe for work content only + */ + nsfw_safe = 2, + + /** + * @brief Age restricted, 18+ + */ + nsfw_age_restricted = 3 }; /** @@ -568,22 +842,35 @@ enum guild_nsfw_level_t : uint8_t { * partnered, official etc. */ enum guild_explicit_content_t : uint8_t { - /// media content will not be scanned - expl_disabled = 0, - /// media content sent by members without roles will be scanned - expl_members_without_roles = 1, - /// media content sent by all members will be scanned - expl_all_members = 2 + /** + * @brief Media content will not be scanned. + */ + expl_disabled = 0, + + /** + * @brief Media content sent by members without roles will be scanned. + */ + expl_members_without_roles = 1, + + /** + * @brief Media content sent by all members will be scanned. + */ + expl_all_members = 2 }; /** - * @brief MFA level for server. If set to elevated all moderators need MFA to perform specific - * actions such as kick or ban. + * @brief MFA level for server. + * If set to elevated all moderators need MFA to perform specific actions such as kick or ban. */ enum mfa_level_t : uint8_t { - /// MFA not elevated + /** + * @brief MFA not elevated + */ mfa_none = 0, - /// MFA elevated + + /** + * @brief MFA elevated. + */ mfa_elevated = 1 }; @@ -591,61 +878,109 @@ enum mfa_level_t : uint8_t { * @brief Guild verification level */ enum verification_level_t : uint8_t { - /// unrestricted - ver_none = 0, - /// must have verified email on account - ver_low = 1, - /// must be registered on Discord for longer than 5 minutes - ver_medium = 2, - /// must be a member of the server for longer than 10 minutes - ver_high = 3, - /// must have a verified phone number + /** + * @brief Unrestricted. + */ + ver_none = 0, + + /** + * @brief Must have verified email on account. + */ + ver_low = 1, + + /** + * @brief Must be registered on Discord for longer than 5 minutes. + */ + ver_medium = 2, + + /** + * @brief Must be a member of the server for longer than 10 minutes. + */ + ver_high = 3, + + /** + * @brief Must have a verified phone number. + */ ver_very_high = 4, }; /** * @brief Default message notification level */ -enum default_message_notification_t: uint8_t { - /// members will receive notifications for all messages by default +enum default_message_notification_t : uint8_t { + /** + * @brief Members will receive notifications for all messages by default. + */ dmn_all = 0, - /// members will receive notifications only for messages that \@mention them by default + + /** + * @brief Members will receive notifications only for messages that \@mention them by default. + */ dmn_only_mentions = 1, }; /** - * @brief Premium tier + * @brief The guild's premium tier. */ -enum guild_premium_tier_t: uint8_t { - /// guild has not unlocked any Server Boost perks +enum guild_premium_tier_t : uint8_t { + /** + * @brief Guild has not unlocked any Server Boost perks. + */ tier_none = 0, - /// guild has unlocked Server Boost level 1 perks + + /** + * @brief Guild has unlocked Server Boost level 1 perks. + */ tier_1 = 1, - /// guild has unlocked Server Boost level 2 perks + + /** + * @brief Guild has unlocked Server Boost level 2 perks. + */ tier_2 = 2, - /// guild has unlocked Server Boost level 3 perks + + /** + * @brief Guild has unlocked Server Boost level 3 perks. + */ tier_3 = 3, }; /** * @brief Voice AFK timeout values for guild::afk_timeout */ -enum guild_afk_timeout_t: uint8_t { - /// AFK timeout disabled +enum guild_afk_timeout_t : uint8_t { + /** + * @brief AFK timeout disabled + */ afk_off, - /// AFK timeout of 1 Minute + + /** + * @brief AFK timeout of 1 Minute + */ afk_60, - /// AFK timeout of 5 Minutes + + /** + * @brief AFK timeout of 5 Minutes + */ afk_300, - /// AFK timeout of 15 Minutes + + /** + * @brief AFK timeout of 15 Minutes + */ afk_900, - /// AFK timeout of 30 Minutes + + /** + * @brief AFK timeout of 30 Minutes + */ afk_1800, - /// AFK timeout of 1 Hour + + /** + * @brief AFK timeout of 1 Hour + */ afk_3600, }; -/** @brief Guild members container +/** + * @brief Guild members container */ typedef std::unordered_map members_container; @@ -671,10 +1006,14 @@ class DPP_EXPORT guild : public managed, public json_interface { public: using json_interface::fill_from_json; - /** Guild name */ + /** + * @brief Guild name + */ std::string name; - /** Server description */ + /** + * @brief Server description + */ std::string description; /** @@ -685,74 +1024,114 @@ class DPP_EXPORT guild : public managed, public json_interface { */ std::string vanity_url_code; - /** Roles defined on this server */ + /** + * @brief Roles defined on this server + */ std::vector roles; - /** List of channels on this server */ + /** + * @brief List of channels on this server + */ std::vector channels; - /** List of threads on this server */ + /** + * @brief List of threads on this server + */ std::vector threads; - /** List of emojis - */ + /** + * @brief List of emojis + */ std::vector emojis; - /** List of members in voice channels in the guild. + /** + * @brief List of members in voice channels in the guild. */ std::map voice_members; - /** List of guild members. Note that when you first receive the - * guild create event, this may be empty or near empty. - * This depends upon your dpp::intents and the size of your bot. + /** + * @brief List of guild members. + * + * @note When you first receive the guild create event, + * this may be empty or near empty. This depends upon your + * dpp::intents and the size of your bot. * It will be filled by guild member chunk requests. */ members_container members; - /** Welcome screen + /** + * @brief Welcome screen */ dpp::welcome_screen welcome_screen; - /** Guild icon */ + /** + * @brief Guild icon + */ utility::icon icon; - /** Guild splash */ + /** + * @brief Guild splash + */ utility::icon splash; - /** Guild discovery splash */ + /** + * @brief Guild discovery splash + */ utility::icon discovery_splash; - /** Server banner */ + /** + * @brief Server banner + */ utility::icon banner; - /** Snowflake id of guild owner */ + /** + * @brief Snowflake id of guild owner + */ snowflake owner_id; - /** Snowflake ID of AFK voice channel or 0 */ + /** + * @brief Snowflake ID of AFK voice channel or 0 + */ snowflake afk_channel_id; - /** ID of creating application, if any, or 0 */ + /** + * @brief ID of creating application, if any, or 0 + */ snowflake application_id; - /** ID of system channel where discord update messages are sent */ + /** + * @brief ID of system channel where discord update messages are sent + */ snowflake system_channel_id; - /** ID of rules channel for communities */ + /** + * @brief ID of rules channel for communities + */ snowflake rules_channel_id; - /** Public updates channel id or 0 */ + /** + * @brief Public updates channel id or 0 + */ snowflake public_updates_channel_id; - /** Snowflake ID of widget channel, or 0 */ + /** + * @brief Snowflake ID of widget channel, or 0 + */ snowflake widget_channel_id; - /** The id of the channel where admins and moderators of Community guilds receive safety alerts from Discord */ + /** + * @brief The id of the channel where admins and moderators of Community guilds receive safety alerts from Discord + */ snowflake safety_alerts_channel_id; - /** Approximate member count. May be sent as zero */ + /** + * @brief Approximate member count. May be sent as zero + */ uint32_t member_count; - /** Flags bitmask as defined by values within dpp::guild_flags */ + /** + * @brief Flags bitmask as defined by values within dpp::guild_flags + */ uint32_t flags; /** @@ -771,31 +1150,49 @@ class DPP_EXPORT guild : public managed, public json_interface { */ uint16_t flags_extra; - /** Shard ID of the guild */ + /** + * @brief Shard ID of the guild + */ uint16_t shard_id; - /** Number of boosters */ + /** + * @brief Number of boosters + */ uint16_t premium_subscription_count; - /** Voice AFK timeout before moving users to AFK channel */ + /** + * @brief Voice AFK timeout before moving users to AFK channel + */ guild_afk_timeout_t afk_timeout; - /** Maximum users in a video channel, or 0 */ + /** + * @brief Maximum users in a video channel, or 0 + */ uint8_t max_video_channel_users; - /** Setting for how notifications are to be delivered to users */ + /** + * @brief Setting for how notifications are to be delivered to users + */ default_message_notification_t default_message_notifications; - /** Boost level */ + /** + * @brief Boost level + */ guild_premium_tier_t premium_tier; - /** Verification level of server */ + /** + * @brief Verification level of server + */ verification_level_t verification_level; - /** Whether or not explicit content filtering is enable and what setting it is */ + /** + * @brief Whether or not explicit content filtering is enable and what setting it is + */ guild_explicit_content_t explicit_content_filter; - /** If multi factor authentication is required for moderators or not */ + /** + * @brief If multi factor authentication is required for moderators or not + */ mfa_level_t mfa_level; /** @@ -1262,7 +1659,9 @@ class DPP_EXPORT guild : public managed, public json_interface { bool has_invites_disabled() const; }; -/** A container of guilds */ +/** + * @brief A container of guilds + */ typedef std::unordered_map guild_map; /** @@ -1308,32 +1707,58 @@ class DPP_EXPORT guild_widget : public json_interface { /** * @brief The onboarding mode for the dpp::onboarding object. Defines the criteria used to satisfy Onboarding constraints that are required for enabling. */ -enum onboarding_mode: uint8_t { - gom_default = 0, //!< Counts only Default Channels towards constraints - gom_advanced = 1, //!< Counts Default Channels and Questions towards constraints +enum onboarding_mode : uint8_t { + /** + * @brief Counts only Default Channels towards constraints. + */ + gom_default = 0, + + /** + * @brief Counts Default Channels and Questions towards constraints. + */ + gom_advanced = 1, }; /** * @brief The various types of dpp::onboarding_prompt */ -enum onboarding_prompt_type: uint8_t { - opt_multiple_choice = 0, //!< Multiple choice - opt_dropdown = 1, //!< Dropdown +enum onboarding_prompt_type : uint8_t { + /** + * @brief Multiple choice. + */ + opt_multiple_choice = 0, + + /** + * @brief Dropdown. + */ + opt_dropdown = 1, }; /** * @brief Various flags for dpp::onboarding_prompt */ -enum onboarding_prompt_flags: uint8_t { - opf_single_select = 1 << 0, //!< Indicates whether users are limited to selecting one option for the prompt - opf_required = 1 << 1, //!< Indicates whether the prompt is required before a user completes the onboarding flow - opf_in_onboarding = 1 << 2, //!< Indicates whether the prompt is present in the onboarding flow. If set, the prompt will only appear in the Channels & Roles tab +enum onboarding_prompt_flags : uint8_t { + /** + * @brief Indicates whether users are limited to selecting one option for the prompt. + */ + opf_single_select = 1 << 0, + + /** + * @brief Indicates whether the prompt is required before a user completes the onboarding flow. + */ + opf_required = 1 << 1, + + /** + * @brief Indicates whether the prompt is present in the onboarding flow. + * If set, the prompt will only appear in the Channels & Roles tab + */ + opf_in_onboarding = 1 << 2, }; /** * @brief Represents an onboarding prompt option */ -struct DPP_EXPORT onboarding_prompt_option: public managed, public json_interface { +struct DPP_EXPORT onboarding_prompt_option : public managed, public json_interface { protected: friend struct json_interface; @@ -1354,11 +1779,30 @@ struct DPP_EXPORT onboarding_prompt_option: public managed, public json_interfac json to_json_impl(bool with_id = false) const; public: - std::vector channel_ids; //!< IDs for channels a member is added to when the option is selected - std::vector role_ids; //!< IDs for roles assigned to a member when the option is selected - dpp::emoji emoji; //!< Emoji of the option - std::string title; //!< Title of the option - std::string description; //!< Description of the option + /** + * @brief IDs for channels a member is added to when the option is selected. + */ + std::vector channel_ids; + + /** + * @brief IDs for roles assigned to a member when the option is selected + */ + std::vector role_ids; + + /** + * @brief Emoji of the option + */ + dpp::emoji emoji; + + /** + * @brief Title of the option + */ + std::string title; + + /** + * @brief Description of the option + */ + std::string description; /** * @brief Construct a new onboarding prompt option object @@ -1398,7 +1842,7 @@ struct DPP_EXPORT onboarding_prompt_option: public managed, public json_interfac /** * @brief Represents an onboarding prompt */ -struct DPP_EXPORT onboarding_prompt: public managed, public json_interface { +struct DPP_EXPORT onboarding_prompt : public managed, public json_interface { protected: friend struct json_interface; @@ -1419,10 +1863,25 @@ struct DPP_EXPORT onboarding_prompt: public managed, public json_interface options; //!< Options available within the prompt - std::string title; //!< Title of the prompt - uint8_t flags; //!< A set of flags built from the bitmask defined by dpp::onboarding_prompt_flags + /** + * @brief Type of prompt (defaults to dpp::opt_multiple_choice). + */ + onboarding_prompt_type type; + + /** + * @brief Options available within the prompt + */ + std::vector options; + + /** + * @brief Title of the prompt. + */ + std::string title; + + /** + * @brief A set of flags built from the bitmask defined by dpp::onboarding_prompt_flags + */ + uint8_t flags; /** * @brief Construct a new onboarding prompt object @@ -1472,7 +1931,7 @@ struct DPP_EXPORT onboarding_prompt: public managed, public json_interface { +struct DPP_EXPORT onboarding : public json_interface { protected: friend struct json_interface; @@ -1493,11 +1952,30 @@ struct DPP_EXPORT onboarding: public json_interface { json to_json_impl(bool with_id = false) const; public: - snowflake guild_id; //!< ID of the guild this onboarding is part of - std::vector prompts; //!< Prompts shown during onboarding and in customize community - std::vector default_channel_ids; //!< Channel IDs that members get opted into automatically - onboarding_mode mode; //!< Current mode of onboarding (defaults to dpp::gom_default) - bool enabled; //!< Whether onboarding is enabled in the guild + /** + * @brief ID of the guild this onboarding is part of. + */ + snowflake guild_id; + + /** + * @brief Prompts shown during onboarding and in customize community. + */ + std::vector prompts; + + /** + * @brief Channel IDs that members get opted into automatically + */ + std::vector default_channel_ids; + + /** + * @brief Current mode of onboarding (defaults to dpp::gom_default) + */ + onboarding_mode mode; + + /** + * @brief Whether onboarding is enabled in the guild + */ + bool enabled; /** * @brief Construct a new onboarding object @@ -1544,7 +2022,9 @@ struct DPP_EXPORT onboarding: public json_interface { */ void from_json(const nlohmann::json& j, guild_member& gm); -/** A container of guild members */ +/** + * @brief A container of guild members + */ typedef std::unordered_map guild_member_map; /** diff --git a/include/dpp/httpsclient.h b/include/dpp/httpsclient.h index d9ca9e582a..f043d533f7 100644 --- a/include/dpp/httpsclient.h +++ b/include/dpp/httpsclient.h @@ -96,6 +96,7 @@ struct multipart_content { * @brief Multipart body */ std::string body; + /** * @brief MIME type */ @@ -111,14 +112,17 @@ struct http_connect_info { * @brief True if the connection should be SSL */ bool is_ssl; + /** * @brief The request scheme, e.g. 'https' or 'http' */ std::string scheme; + /** * @brief The request hostname part, e.g. 'discord.com' */ std::string hostname; + /** * @brief The port number, either determined from the scheme, * or from the part of the hostname after a colon ":" character @@ -130,8 +134,7 @@ struct http_connect_info { * @brief Implements a HTTPS socket client based on the SSL client. * @note plaintext HTTP without SSL is also supported via a "downgrade" setting */ -class DPP_EXPORT https_client : public ssl_client -{ +class DPP_EXPORT https_client : public ssl_client { /** * @brief Current connection state */ @@ -215,7 +218,6 @@ class DPP_EXPORT https_client : public ssl_client bool do_buffer(std::string& buffer); protected: - /** * @brief Start the connection */ @@ -228,7 +230,6 @@ class DPP_EXPORT https_client : public ssl_client http_state get_state(); public: - /** * @brief Connect to a specific HTTP(S) server and complete a request. * diff --git a/include/dpp/integration.h b/include/dpp/integration.h index 98d5cb507d..1e48c7be65 100644 --- a/include/dpp/integration.h +++ b/include/dpp/integration.h @@ -34,13 +34,24 @@ namespace dpp { * @brief Integration types */ enum integration_type { - /// Twitch integration + /** + * @brief Twitch integration + */ i_twitch, - /// YouTube integration + + /** + * @brief YouTube integration + */ i_youtube, - /// Discord integration + + /** + * @brief Discord integration + */ i_discord, - /// Subscription + + /** + * @brief Subscription + */ i_guild_subscription, }; @@ -48,30 +59,79 @@ enum integration_type { * @brief Integration flags */ enum integration_flags { - if_enabled = 0b00000001, //!< is this integration enabled - if_syncing = 0b00000010, //!< is this integration syncing @warning This is not provided for discord bot integrations. - if_emoticons = 0b00000100, //!< whether emoticons should be synced for this integration (twitch only currently) @warning This is not provided for discord bot integrations. - if_revoked = 0b00001000, //!< has this integration been revoked @warning This is not provided for discord bot integrations. - if_expire_kick = 0b00010000, //!< kick user when their subscription expires, otherwise only remove the role that is specified by `role_id`. @warning This is not provided for discord bot integrations. + /** + * @brief Is this integration enabled? + */ + if_enabled = 0b00000001, + + /** + * @brief Is this integration syncing? + * @warning This is not provided for discord bot integrations. + */ + if_syncing = 0b00000010, + + /** + * @brief Whether emoticons should be synced for this integration (twitch only currently). + * @warning This is not provided for discord bot integrations. + */ + if_emoticons = 0b00000100, + + /** + * @brief Has this integration been revoked? + * @warning This is not provided for discord bot integrations. + */ + if_revoked = 0b00001000, + + /** + * @brief Kick user when their subscription expires, otherwise only remove the role that is specified by `role_id`. + * @warning This is not provided for discord bot integrations. + */ + if_expire_kick = 0b00010000, }; /** * @brief An application that has been integrated */ struct DPP_EXPORT integration_app { - snowflake id; //!< the id of the app - std::string name; //!< the name of the app - utility::iconhash icon; //!< the icon hash of the app - std::string description; //!< the description of the app - class user* bot; //!< the bot associated with this application + /** + * @brief The id of the app. + */ + snowflake id; + + /** + * @brief The name of the app. + */ + std::string name; + + /** + * @brief The icon hash of the app. + */ + utility::iconhash icon; + + /** + * @brief The description of the app + */ + std::string description; + + /** + * @brief The bot associated with this application. + */ + class user* bot; }; /** * @brief The account information for an integration. */ struct DPP_EXPORT integration_account { - snowflake id; //!< id of the account - std::string name; //!< name of the account + /** + * @brief ID of the account + */ + snowflake id; + + /** + * @brief Name of the account. + */ + std::string name; }; /** @@ -94,17 +154,68 @@ class DPP_EXPORT integration : public managed, public json_interface scopes; //!< the scopes the application has been authorized for + /** + * @brief Integration name. + */ + std::string name; + + /** + * @brief Integration type (twitch, youtube, discord, or guild_subscription). + */ + integration_type type; + + /** + * @brief Integration flags from dpp::integration_flags + */ + uint8_t flags; + + /** + * @brief ID that this integration uses for "subscribers". + * + * @warning This is not provided for discord bot integrations. + */ + snowflake role_id; + + /** + * @brief The grace period (in days) before expiring subscribers. + * + * @warning This is not provided for discord bot integrations. + */ + uint32_t expire_grace_period; + + /** + * @brief User for this integration + */ + user user_obj; + + /** + * @brief Integration account information + */ + integration_account account; + + /** + * @brief When this integration was last synced. + * + * @warning This is not provided for discord bot integrations. + */ + time_t synced_at; + + /** + * @brief How many subscribers this integration has. + * + * @warning This is not provided for discord bot integrations. + */ + uint32_t subscriber_count; + + /** + * @brief The bot/OAuth2 application for discord integrations. + */ + integration_app app; + + /** + * @brief The scopes the application has been authorized for. + */ + std::vector scopes; /** Default constructor */ integration(); @@ -158,16 +269,55 @@ class DPP_EXPORT connection : public json_interface { connection& fill_from_json_impl(nlohmann::json* j); public: - std::string id; //!< id of the connection account - std::string name; //!< the username of the connection account - std::string type; //!< the service of the connection (twitch, youtube, discord, or guild_subscription) - bool revoked; //!< Optional: whether the connection is revoked - std::vector integrations; //!< Optional: an array of partial server integrations - bool verified; //!< whether the connection is verified - bool friend_sync; //!< whether friend sync is enabled for this connection - bool show_activity; //!< whether activities related to this connection will be shown in presence updates - bool two_way_link; //!< Whether this connection has a corresponding third party OAuth2 token - bool visible; //!< visibility of this connection + /** + * @brief ID of the connection account. + */ + std::string id; + + /** + * @brief the username of the connection account. + */ + std::string name; + + /** + * @brief the service of the connection (twitch, youtube, discord, or guild_subscription). + */ + std::string type; + + /** + * @brief Optional: whether the connection is revoked. + */ + bool revoked; + + /** + * @brief Optional: an array of partial server integrations. + */ + std::vector integrations; + + /** + * @brief Whether the connection is verified. + */ + bool verified; + + /** + * @brief Whether friend sync is enabled for this connection. + */ + bool friend_sync; + + /** + * @brief Whether activities related to this connection will be shown in presence updates. + */ + bool show_activity; + + /** + * @brief Whether this connection has a corresponding third party OAuth2 token. + */ + bool two_way_link; + + /** + * @brief Visibility of this connection. + */ + bool visible; /** * @brief Construct a new connection object @@ -175,10 +325,14 @@ class DPP_EXPORT connection : public json_interface { connection(); }; -/** A group of integrations */ +/** + * @brief A group of integrations + */ typedef std::unordered_map integration_map; -/** A group of connections */ +/** + * @brief A group of connections + */ typedef std::unordered_map connection_map; } // namespace dpp diff --git a/include/dpp/intents.h b/include/dpp/intents.h index 80bc94bba2..d225a9d5e1 100644 --- a/include/dpp/intents.h +++ b/include/dpp/intents.h @@ -31,56 +31,124 @@ namespace dpp { * your real life ID. */ enum intents { - /// Intent for receipt of guild information + /** + * @brief Intent for receipt of guild information. + */ i_guilds = (1 << 0), - /// Intent for receipt of guild members + + /** + * @brief Intent for receipt of guild members. + */ i_guild_members = (1 << 1), - /// Intent for receipt of guild bans + + /** + * @brief Intent for receipt of guild bans. + */ i_guild_bans = (1 << 2), - /// Intent for receipt of guild emojis + + /** + * @brief Intent for receipt of guild emojis. + */ i_guild_emojis = (1 << 3), - /// Intent for receipt of guild integrations + + /** + * @brief Intent for receipt of guild integrations. + */ i_guild_integrations = (1 << 4), - /// Intent for receipt of guild webhooks + + /** + * @brief Intent for receipt of guild webhooks. + */ i_guild_webhooks = (1 << 5), - /// Intent for receipt of guild invites + + /** + * @brief Intent for receipt of guild invites. + */ i_guild_invites = (1 << 6), - /// Intent for receipt of guild voice states + + /** + * @brief Intent for receipt of guild voice states. + */ i_guild_voice_states = (1 << 7), - /// Intent for receipt of guild presences + + /** + * @brief Intent for receipt of guild presences. + */ i_guild_presences = (1 << 8), - /// Intent for receipt of guild messages + + /** + * @brief Intent for receipt of guild messages. + */ i_guild_messages = (1 << 9), - /// Intent for receipt of guild message reactions + + /** + * @brief Intent for receipt of guild message reactions. + */ i_guild_message_reactions = (1 << 10), - /// Intent for receipt of guild message typing notifications + + /** + * @brief Intent for receipt of guild message typing notifications. + */ i_guild_message_typing = (1 << 11), - /// Intent for receipt of direct messages (DMs) + + /** + * @brief Intent for receipt of direct messages (DMs). + */ i_direct_messages = (1 << 12), - /// Intent for receipt of direct message reactions + + /** + * @brief Intent for receipt of direct message reactions. + */ i_direct_message_reactions = (1 << 13), - /// Intent for receipt of direct message typing notifications + + /** + * @brief Intent for receipt of direct message typing notifications. + */ i_direct_message_typing = (1 << 14), - /// Intent for receipt of message content + + /** + * @brief Intent for receipt of message content. + */ i_message_content = (1 << 15), - /// Scheduled events + + /** + * @brief Scheduled events. + */ i_guild_scheduled_events = (1 << 16), - /// Auto moderation configuration + + /** + * @brief Auto moderation configuration. + */ i_auto_moderation_configuration = (1 << 20), - /// Auto moderation configuration + + /** + * @brief Auto moderation configuration. + */ i_auto_moderation_execution = (1 << 21), - /// Default D++ intents (all non-privileged intents) + + /** + * @brief Default D++ intents (all non-privileged intents). + */ i_default_intents = dpp::i_guilds | dpp::i_guild_bans | dpp::i_guild_emojis | dpp::i_guild_integrations | dpp::i_guild_webhooks | dpp::i_guild_invites | dpp::i_guild_voice_states | dpp::i_guild_messages | dpp::i_guild_message_reactions | dpp::i_guild_message_typing | dpp::i_direct_messages | dpp::i_direct_message_typing | dpp::i_direct_message_reactions | dpp::i_guild_scheduled_events | dpp::i_auto_moderation_configuration | - dpp::i_auto_moderation_execution, - /// Privileged intents requiring ID + dpp::i_auto_moderation_execution, + + /** + * @brief Privileged intents requiring ID. + */ i_privileged_intents = dpp::i_guild_members | dpp::i_guild_presences | dpp::i_message_content, - /// Every single intent + + /** + * @brief Every single intent (dpp::i_default_intents and dpp::i_privileged_intents). + */ i_all_intents = dpp::i_default_intents | dpp::i_privileged_intents, - /// Unverified bots default intents + + /** + * @brief Unverified bots default intents. + */ i_unverified_default_intents = dpp::i_default_intents | dpp::i_message_content }; diff --git a/include/dpp/invite.h b/include/dpp/invite.h index 37798ec410..c20708056a 100644 --- a/include/dpp/invite.h +++ b/include/dpp/invite.h @@ -36,9 +36,20 @@ namespace dpp { * @brief Invite target types for dpp::invite */ enum invite_target_t : uint8_t { - itt_none = 0, //!< Undefined invite target type - itt_stream = 1, //!< Stream target type - itt_embedded_application = 2, //!< Embedded Application target type + /** + * @brief Undefined invite target type. + */ + itt_none = 0, + + /** + * @brief Stream target type. + */ + itt_stream = 1, + + /** + * @brief Embedded Application target type. + */ + itt_embedded_application = 2, }; /** @@ -61,74 +72,119 @@ class DPP_EXPORT invite : public json_interface { virtual json to_json_impl(bool with_id = false) const; public: - /** Invite code + /** + * @brief Invite code. */ std::string code; - /** Readonly expiration timestamp of this invite or 0 if the invite doesn't expire + + /** + * @brief Readonly expiration timestamp of this invite or 0 if the invite doesn't expire. * @note Only returned from cluster::invite_get */ time_t expires_at; - /** Guild ID this invite is for + + /** + * @brief Guild ID this invite is for. */ snowflake guild_id; - /** The partial guild this invite is for. Only filled in retrieved invites + + /** + * @brief The partial guild this invite is for. + * @note Only filled in retrieved invites. */ guild destination_guild; - /** Channel ID this invite is for + + /** + * @brief Channel ID this invite is for. */ snowflake channel_id; - /** The partial channel this invite is for. Only filled in retrieved invites + + /** + * @brief The partial channel this invite is for. + * @note Only filled in retrieved invites. */ channel destination_channel; - /** User ID who created this invite + + /** + * @brief User ID who created this invite. * @deprecated Use the `inviter` field instead */ snowflake inviter_id; - /** User who created this invite + + /** + * @brief User who created this invite. */ user inviter; - /** The user ID whose stream to display for this voice channel stream invite + + /** + * @brief The user ID whose stream to display for this voice channel stream invite. */ snowflake target_user_id; - /** Target type for this voice channel invite + + /** + * @brief Target type for this voice channel invite. */ invite_target_t target_type; - /** Approximate number of online users + + /** + * @brief Approximate number of online users. * @note Only returned from cluster::invite_get */ uint32_t approximate_presence_count; - /** Approximate number of total users online and offline - * @note Only returned from cluster::invite_get + + /** + * @brief Approximate number of total users online and offline. + * @note Only returned from cluster::invite_get. */ uint32_t approximate_member_count; - /** Duration (in seconds) after which the invite expires, or 0 for no expiration. Must be between 0 and 604800 (7 days). Defaults to 86400 (1 day) + + /** + * @brief Duration (in seconds) after which the invite expires, or 0 for no expiration. Defaults to 86400 (1 day). + * + * @note Must be between 0 and 604800 (7 days). */ uint32_t max_age; - /** Maximum number of uses, or 0 for unlimited. Must be between 0 and 100. Defaults to 0 + + /** + * @brief Maximum number of uses, or 0 for unlimited. Defaults to 0. + * + * @note Must be between 0 and 100. */ uint8_t max_uses; - /** Whether this invite only grants temporary membership + + /** + * @brief Whether this invite only grants temporary membership. */ bool temporary; - /** True if this invite should not replace or "attach to" similar invites + + /** + * @brief True if this invite should not replace or "attach to" similar invites. */ bool unique; - /** How many times this invite has been used + + /** + * @brief How many times this invite has been used. */ uint32_t uses; - /** The stage instance data if there is a public stage instance in the stage channel this invite is for + + /** + * @note The stage instance data if there is a public stage instance in the stage channel this invite is for. * @deprecated Deprecated */ stage_instance stage; - /** Timestamp at which the invite was created + + /** + * @brief Timestamp at which the invite was created. */ time_t created_at; - /** Constructor + /** + * @brief Constructor. */ invite(); - /** Destructor + /** + * @brief Destructor. */ virtual ~invite() = default; @@ -181,7 +237,9 @@ class DPP_EXPORT invite : public json_interface { invite& set_unique(const bool is_unique); }; -/** A container of invites */ +/** + * @brief A container of invites + */ typedef std::unordered_map invite_map; } // namespace dpp diff --git a/include/dpp/json_interface.h b/include/dpp/json_interface.h index a5c5fbd3e5..5c3fb69c36 100644 --- a/include/dpp/json_interface.h +++ b/include/dpp/json_interface.h @@ -24,48 +24,50 @@ #include namespace dpp { + +/** + * @brief Represents an interface for an object that can optionally implement functions + * for converting to and from nlohmann::json. The methods are only present if the actual object + * also has those methods. + * + * @tparam T Type of class that implements the interface + */ +template +struct DPP_EXPORT json_interface { /** - * @brief Represents an interface for an object that can optionally implement functions - * for converting to and from nlohmann::json. The methods are only present if the actual object - * also has those methods. + * @brief Convert object from nlohmann::json * - * @tparam T Type of class that implements the interface + * @param j nlohmann::json object + * @return T& Reference to self for fluent calling */ - template - struct DPP_EXPORT json_interface { - /** - * @brief Convert object from nlohmann::json - * - * @param j nlohmann::json object - * @return T& Reference to self for fluent calling - */ - template ().fill_from_json_impl(std::declval()))> - T& fill_from_json(nlohmann::json* j) { - return static_cast(this)->fill_from_json_impl(j); - } + template ().fill_from_json_impl(std::declval()))> + T& fill_from_json(nlohmann::json* j) { + return static_cast(this)->fill_from_json_impl(j); + } - /** - * @brief Convert object to nlohmann::json - * - * @param with_id Whether to include the ID or not - * @note Some fields are conditionally filled, do not rely on all fields being present - * @return json Json built from the structure - */ - template ().to_json_impl(bool{}))> - auto to_json(bool with_id = false) const { - return static_cast(this)->to_json_impl(with_id); - } + /** + * @brief Convert object to nlohmann::json + * + * @param with_id Whether to include the ID or not + * @note Some fields are conditionally filled, do not rely on all fields being present + * @return json Json built from the structure + */ + template ().to_json_impl(bool{}))> + auto to_json(bool with_id = false) const { + return static_cast(this)->to_json_impl(with_id); + } + + /** + * @brief Convert object to json string + * + * @param with_id Whether to include the ID or not + * @note Some fields are conditionally filled, do not rely on all fields being present + * @return std::string Json built from the structure + */ + template ().to_json_impl(bool{}))> + std::string build_json(bool with_id = false) const { + return to_json(with_id).dump(); + } +}; - /** - * @brief Convert object to json string - * - * @param with_id Whether to include the ID or not - * @note Some fields are conditionally filled, do not rely on all fields being present - * @return std::string Json built from the structure - */ - template ().to_json_impl(bool{}))> - std::string build_json(bool with_id = false) const { - return to_json(with_id).dump(); - } - }; } // namespace dpp diff --git a/include/dpp/managed.h b/include/dpp/managed.h index 86188f7da8..4ccd2e5318 100644 --- a/include/dpp/managed.h +++ b/include/dpp/managed.h @@ -26,91 +26,91 @@ namespace dpp { - /** @brief The managed class is the base class for various types that can - * be stored in a cache that are identified by a dpp::snowflake id. +/** @brief The managed class is the base class for various types that can + * be stored in a cache that are identified by a dpp::snowflake id. + */ +class DPP_EXPORT managed { +public: + /** + * @brief Unique ID of object set by Discord. + * This value contains a timestamp, worker ID, internal server ID, and an incrementing value. + * Only the timestamp is relevant to us as useful metadata. */ - class DPP_EXPORT managed { - public: - /** - * @brief Unique ID of object set by Discord. - * This value contains a timestamp, worker ID, internal server ID, and an incrementing value. - * Only the timestamp is relevant to us as useful metadata. - */ - snowflake id = {}; + snowflake id = {}; - /** - * @brief Constructor, initialises id to 0. - */ - managed() = default; + /** + * @brief Constructor, initialises id to 0. + */ + managed() = default; - /** - * @brief Constructor, initialises ID - * @param nid ID to set - */ - managed(const snowflake nid) : id{nid} {} + /** + * @brief Constructor, initialises ID + * @param nid ID to set + */ + managed(const snowflake nid) : id{nid} {} - /** - * @brief Copy constructor - * @param rhs Object to copy - */ - managed(const managed &rhs) = default; + /** + * @brief Copy constructor + * @param rhs Object to copy + */ + managed(const managed &rhs) = default; - /** - * @brief Move constructor - * - * Effectively equivalent to copy constructor - * @param rhs Object to move from - */ - managed(managed &&rhs) = default; + /** + * @brief Move constructor + * + * Effectively equivalent to copy constructor + * @param rhs Object to move from + */ + managed(managed &&rhs) = default; - /** - * @brief Destroy the managed object - */ - virtual ~managed() = default; + /** + * @brief Destroy the managed object + */ + virtual ~managed() = default; - /** - * @brief Copy assignment operator - * @param rhs Object to copy - */ - managed &operator=(const managed& rhs) = default; + /** + * @brief Copy assignment operator + * @param rhs Object to copy + */ + managed &operator=(const managed& rhs) = default; - /** - * @brief Move assignment operator - * @param rhs Object to move from - */ - managed &operator=(managed&& rhs) = default; + /** + * @brief Move assignment operator + * @param rhs Object to move from + */ + managed &operator=(managed&& rhs) = default; - /** - * @brief Get the creation time of this object according to Discord. - * - * @return double creation time inferred from the snowflake ID. - * The minimum possible value is the first second of 2015. - */ - constexpr double get_creation_time() const noexcept { - return id.get_creation_time(); - }; + /** + * @brief Get the creation time of this object according to Discord. + * + * @return double creation time inferred from the snowflake ID. + * The minimum possible value is the first second of 2015. + */ + constexpr double get_creation_time() const noexcept { + return id.get_creation_time(); + }; - /** - * @brief Comparison operator for comparing two managed objects by id - * - * @param other Other object to compare against - * @return true objects are the same id - * @return false objects are not the same id - */ - constexpr bool operator==(const managed& other) const noexcept { - return id == other.id; - } + /** + * @brief Comparison operator for comparing two managed objects by id + * + * @param other Other object to compare against + * @return true objects are the same id + * @return false objects are not the same id + */ + constexpr bool operator==(const managed& other) const noexcept { + return id == other.id; + } - /** - * @brief Comparison operator for comparing two managed objects by id - * - * @param other Other object to compare against - * @return true objects are not the same id - * @return false objects are the same id - */ - constexpr bool operator!=(const managed& other) const noexcept { - return id != other.id; - } - }; + /** + * @brief Comparison operator for comparing two managed objects by id + * + * @param other Other object to compare against + * @return true objects are not the same id + * @return false objects are the same id + */ + constexpr bool operator!=(const managed& other) const noexcept { + return id != other.id; + } +}; } // namespace dpp diff --git a/include/dpp/misc-enum.h b/include/dpp/misc-enum.h index fd608953c5..feb84b6329 100644 --- a/include/dpp/misc-enum.h +++ b/include/dpp/misc-enum.h @@ -25,32 +25,65 @@ namespace dpp { - /** @brief Supported image types for profile pictures and CDN endpoints */ - enum image_type { - /// image/png - i_png, - /// image/jpeg - i_jpg, - /// image/gif - i_gif, - /// WebP - i_webp, - }; - - /** @brief Log levels */ - enum loglevel { - /// Trace - ll_trace = 0, - /// Debug - ll_debug, - /// Information - ll_info, - /// Warning - ll_warning, - /// Error - ll_error, - /// Critical - ll_critical - }; +/** + * @brief Supported image types for profile pictures and CDN endpoints + */ +enum image_type { + /** + * @brief image/png + */ + i_png, + + /** + * @brief image/jpeg. + */ + i_jpg, + + /** + * @brief image/gif. + */ + i_gif, + + /** + * @brief Webp. + */ + /// WebP + i_webp, +}; + +/** + * @brief Log levels + */ +enum loglevel { + /** + * @brief Trace + */ + ll_trace = 0, + + /** + * @brief Debug + */ + ll_debug, + + /** + * @brief Information + */ + ll_info, + + /** + * @brief Warning + */ + ll_warning, + + /** + * @brief Error + */ + ll_error, + + /** + * @brief Critical + */ + ll_critical +}; } // namespace dpp diff --git a/include/dpp/once.h b/include/dpp/once.h index 4ca494e9af..f81a02cfdb 100644 --- a/include/dpp/once.h +++ b/include/dpp/once.h @@ -24,23 +24,23 @@ namespace dpp { - /** - * @brief Run some code within an if() statement only once. - * - * Use this template like this: - * - * ``` - * if (dpp::run_once()) { - * // Your code here - * } - * ``` - * - * @tparam T any unique 'tag' identifier name - * @return auto a true/false return to say if we should execute or not - */ - template auto run_once() { - static auto called = false; - return !std::exchange(called, true); - }; +/** + * @brief Run some code within an if() statement only once. + * + * Use this template like this: + * + * ``` + * if (dpp::run_once()) { + * // Your code here + * } + * ``` + * + * @tparam T any unique 'tag' identifier name + * @return auto a true/false return to say if we should execute or not + */ +template auto run_once() { + static auto called = false; + return !std::exchange(called, true); +}; } // namespace dpp diff --git a/include/dpp/permissions.h b/include/dpp/permissions.h index 0dd9e9b143..22b1b555ba 100644 --- a/include/dpp/permissions.h +++ b/include/dpp/permissions.h @@ -30,52 +30,241 @@ namespace dpp { * @brief Represents the various discord permissions */ enum permissions : uint64_t { - p_create_instant_invite = 0x00000000001, //!< allows creation of instant invites - p_kick_members = 0x00000000002, //!< allows kicking members - p_ban_members = 0x00000000004, //!< allows banning members - p_administrator = 0x00000000008, //!< allows all permissions and bypasses channel permission overwrites - p_manage_channels = 0x00000000010, //!< allows management and editing of channels - p_manage_guild = 0x00000000020, //!< allows management and editing of the guild - p_add_reactions = 0x00000000040, //!< allows for the addition of reactions to messages - p_view_audit_log = 0x00000000080, //!< allows for viewing of audit logs - p_priority_speaker = 0x00000000100, //!< allows for using priority speaker in a voice channel - p_stream = 0x00000000200, //!< allows the user to go live - p_view_channel = 0x00000000400, //!< allows guild members to view a channel, which includes reading messages in text channels and joining voice channels - p_send_messages = 0x00000000800, //!< allows for sending messages in a channel - p_send_tts_messages = 0x00000001000, //!< allows for sending of /tts messages - p_manage_messages = 0x00000002000, //!< allows for deletion of other users messages - p_embed_links = 0x00000004000, //!< links sent by users with this permission will be auto-embedded - p_attach_files = 0x00000008000, //!< allows for uploading images and files - p_read_message_history = 0x00000010000, //!< allows for reading of message history - p_mention_everyone = 0x00000020000, //!< allows for using the everyone and the here tag to notify users in a channel - p_use_external_emojis = 0x00000040000, //!< allows the usage of custom emojis from other servers - p_view_guild_insights = 0x00000080000, //!< allows for viewing guild insights - p_connect = 0x00000100000, //!< allows for joining of a voice channel - p_speak = 0x00000200000, //!< allows for speaking in a voice channel - p_mute_members = 0x00000400000, //!< allows for muting members in a voice channel - p_deafen_members = 0x00000800000, //!< allows for deafening of members in a voice channel - p_move_members = 0x00001000000, //!< allows for moving of members between voice channels - p_use_vad = 0x00002000000, //!< allows for using voice-activity-detection in a voice channel - p_change_nickname = 0x00004000000, //!< allows for modification of own nickname - p_manage_nicknames = 0x00008000000, //!< allows for modification of other users nicknames - p_manage_roles = 0x00010000000, //!< allows management and editing of roles - p_manage_webhooks = 0x00020000000, //!< allows management and editing of webhooks - p_manage_emojis_and_stickers = 0x00040000000, //!< allows management and editing of emojis and stickers - p_use_application_commands = 0x00080000000, //!< allows members to use application commands, including slash commands and context menus - p_request_to_speak = 0x00100000000, //!< allows for requesting to speak in stage channels. (Discord: This permission is under active development and may be changed or removed.) - p_manage_events = 0x00200000000, //!< allows for management (creation, updating, deleting, starting) of scheduled events - p_manage_threads = 0x00400000000, //!< allows for deleting and archiving threads, and viewing all private threads - p_create_public_threads = 0x00800000000, //!< allows for creating public and announcement threads - p_create_private_threads = 0x01000000000, //!< allows for creating private threads - p_use_external_stickers = 0x02000000000, //!< allows the usage of custom stickers from other servers - p_send_messages_in_threads = 0x04000000000, //!< allows for sending messages in threads - p_use_embedded_activities = 0x08000000000, //!< allows for using activities (applications with the EMBEDDED flag) in a voice channel - p_moderate_members = 0x10000000000, //!< allows for timing out users to prevent them from sending or reacting to messages in chat and threads, and from speaking in voice and stage channels - p_view_creator_monetization_analytics = 0x20000000000, //!< allows for viewing role subscription insights - p_use_soundboard = 0x40000000000, //!< allows for using soundboard in a voice channel - p_use_external_sounds = 0x0000200000000000, //!< allows the usage of custom soundboard sounds from other servers - p_send_voice_messages = 0x0000400000000000, //!< allows sending voice messages - p_use_clyde_ai = 0x0000800000000000, //!< allows use of Clyde AI + /** + * @brief Allows creation of instant invites. + */ + p_create_instant_invite = 0x00000000001, + + /** + * @brief Allows kicking members. + */ + p_kick_members = 0x00000000002, + + /** + * @brief Allows banning members. + */ + p_ban_members = 0x00000000004, + + /** + * @brief Allows all permissions and bypasses channel permission overwrites. + */ + p_administrator = 0x00000000008, + + /** + * @brief Allows management and editing of channels. + */ + p_manage_channels = 0x00000000010, + + /** + * @brief Allows management and editing of the guild. + */ + p_manage_guild = 0x00000000020, + + /** + * @brief Allows for the addition of reactions to messages. + */ + p_add_reactions = 0x00000000040, + + /** + * @brief Allows for viewing of audit logs. + */ + p_view_audit_log = 0x00000000080, + + /** + * @brief Allows for using priority speaker in a voice channel. + */ + p_priority_speaker = 0x00000000100, + + /** + * @brief Allows the user to go live. + */ + p_stream = 0x00000000200, + + /** + * @brief Allows guild members to view a channel, + * which includes reading messages in text channels and joining voice channels. + */ + p_view_channel = 0x00000000400, + + /** + * @brief Allows for sending messages in a channel. + */ + p_send_messages = 0x00000000800, + + /** + * @brief Allows for sending of /tts messages. + */ + p_send_tts_messages = 0x00000001000, + + /** + * @brief Allows for deletion of other users messages. + */ + p_manage_messages = 0x00000002000, + + /** + * @brief Links sent by users with this permission will be auto-embedded. + */ + p_embed_links = 0x00000004000, + + /** + * @brief Allows for uploading images and files. + */ + p_attach_files = 0x00000008000, + + /** + * @brief Allows for reading of message history. + */ + p_read_message_history = 0x00000010000, + + /** + * @brief Allows for using the everyone and the here tag to notify users in a channel. + */ + p_mention_everyone = 0x00000020000, + + /** + * @brief Allows the usage of custom emojis from other servers. + */ + p_use_external_emojis = 0x00000040000, + + /** + * @brief Allows for viewing guild insights. + */ + p_view_guild_insights = 0x00000080000, + + /** + * @brief Allows for joining of a voice channel. + */ + p_connect = 0x00000100000, + + /** + * @brief Allows for speaking in a voice channel. + */ + p_speak = 0x00000200000, + + /** + * @brief Allows for muting members in a voice channel. + */ + p_mute_members = 0x00000400000, + + /** + * @brief Allows for deafening of members in a voice channel. + */ + p_deafen_members = 0x00000800000, + + /** + * @brief Allows for moving of members between voice channels. + */ + p_move_members = 0x00001000000, + + /** + * @brief Allows for using voice-activity-detection in a voice channel. + */ + p_use_vad = 0x00002000000, + + /** + * @brief Allows for modification of own nickname. + */ + p_change_nickname = 0x00004000000, + + /** + * @brief Allows for modification of other users nicknames. + */ + p_manage_nicknames = 0x00008000000, + + /** + * @brief Allows management and editing of roles. + */ + p_manage_roles = 0x00010000000, + + /** + * @brief Allows management and editing of webhooks. + */ + p_manage_webhooks = 0x00020000000, + + /** + * @brief Allows management and editing of emojis and stickers. + */ + p_manage_emojis_and_stickers = 0x00040000000, + + /** + * @brief Allows members to use application commands, + * including slash commands and context menus. + */ + p_use_application_commands = 0x00080000000, + + /** + * @brief Allows for requesting to speak in stage channels. + * + * @warning Discord: This permission is under active development and may be changed or removed. + */ + p_request_to_speak = 0x00100000000, + + /** + * @brief Allows for management (creation, updating, deleting, starting) of scheduled events. + */ + p_manage_events = 0x00200000000, + + /** + * @brief Allows for deleting and archiving threads, and viewing all private threads. + */ + p_manage_threads = 0x00400000000, + + /** + * @brief Allows for creating public and announcement threads. + */ + p_create_public_threads = 0x00800000000, + + /** + * @brief Allows for creating private threads. + */ + p_create_private_threads = 0x01000000000, + + /** + * @brief Allows the usage of custom stickers from other servers. + */ + p_use_external_stickers = 0x02000000000, + + /** + * @brief Allows for sending messages in threads. + */ + p_send_messages_in_threads = 0x04000000000, + + /** + * @brief Allows for using activities (applications with the EMBEDDED flag) in a voice channel. + */ + p_use_embedded_activities = 0x08000000000, + + /** + * @brief Allows for timing out users + * to prevent them from sending or reacting to messages in chat and threads, + * and from speaking in voice and stage channels. + */ + p_moderate_members = 0x10000000000, + + /** + * @brief Allows for viewing role subscription insights. + */ + p_view_creator_monetization_analytics = 0x20000000000, + + /** + * @brief Allows for using soundboard in a voice channel. + */ + p_use_soundboard = 0x40000000000, + + /** + * @brief Allows the usage of custom soundboard sounds from other servers. + */ + p_use_external_sounds = 0x0000200000000000, + + /** + * @brief Allows sending voice messages. + */ + p_send_voice_messages = 0x0000400000000000, + + /** + * @brief Allows use of Clyde AI. + */ + p_use_clyde_ai = 0x0000800000000000, }; /** diff --git a/include/dpp/presence.h b/include/dpp/presence.h index 1dbc09cbf7..7515b14bac 100644 --- a/include/dpp/presence.h +++ b/include/dpp/presence.h @@ -33,84 +33,174 @@ namespace dpp { * @brief Presence flags bitmask */ enum presence_flags { - /// Desktop: Online - p_desktop_online = 0b00000001, - /// Desktop: DND - p_desktop_dnd = 0b00000010, - /// Desktop: Idle - p_desktop_idle = 0b00000011, - /// Web: Online - p_web_online = 0b00000100, - /// Web: DND - p_web_dnd = 0b00001000, - /// Web: Idle - p_web_idle = 0b00001100, - /// Mobile: Online - p_mobile_online = 0b00010000, - /// Mobile: DND - p_mobile_dnd = 0b00100000, - /// Mobile: Idle - p_mobile_idle = 0b00110000, - /// General: Online - p_status_online = 0b01000000, - /// General: DND - p_status_dnd = 0b10000000, - /// General: Idle - p_status_idle = 0b11000000 + /** + * @brief Desktop: Online. + */ + p_desktop_online = 0b00000001, + + /** + * @brief Desktop: DND. + */ + p_desktop_dnd = 0b00000010, + + /** + * @brief Desktop: Idle. + */ + p_desktop_idle = 0b00000011, + + /** + * @brief Web: Online. + */ + p_web_online = 0b00000100, + + /** + * @brief Web: DND. + */ + p_web_dnd = 0b00001000, + + /** + * @brief Web: Idle. + */ + p_web_idle = 0b00001100, + + /** + * @brief Mobile: Online. + */ + p_mobile_online = 0b00010000, + + /** + * @brief Mobile: DND. + */ + p_mobile_dnd = 0b00100000, + + /** + * @brief Mobile: Idle. + */ + p_mobile_idle = 0b00110000, + + /** + * @brief General: Online. + */ + p_status_online = 0b01000000, + + /** + * @brief General: DND. + */ + p_status_dnd = 0b10000000, + + /** + * @brief General: Idle. + */ + p_status_idle = 0b11000000 }; /** * @brief Online presence status values */ enum presence_status : uint8_t { - /// Offline - ps_offline = 0, - /// Online - ps_online = 1, - /// DND - ps_dnd = 2, - /// Idle - ps_idle = 3, - /// Invisible (show as offline) - ps_invisible = 4, + /** + * @brief Offline. + */ + ps_offline = 0, + + /** + * @brief Online. + */ + ps_online = 1, + + /** + * @brief DND. + */ + ps_dnd = 2, + + /** + * @brief Idle. + */ + ps_idle = 3, + + /** + * @brief Invisible (show as offline). + */ + ps_invisible = 4, }; /** - * @brief Bit shift for desktop status + * @brief Bit shift for desktop status. */ #define PF_SHIFT_DESKTOP 0 -/** Bit shift for web status */ + +/** + * @brief Bit shift for web status. + */ #define PF_SHIFT_WEB 2 -/** Bit shift for mobile status */ + +/** + * @brief Bit shift for mobile status. + */ #define PF_SHIFT_MOBILE 4 -/** Bit shift for main status */ + +/** + * @brief Bit shift for main status. + */ #define PF_SHIFT_MAIN 6 -/** Bit mask for status */ + +/** + * @brief Bit mask for status. + */ #define PF_STATUS_MASK 0b00000011 -/** Bit mask for clearing desktop status */ + +/** + * @brief Bit mask for clearing desktop status. + */ #define PF_CLEAR_DESKTOP 0b11111100 -/** Bit mask for clearing web status */ + +/** + * @brief Bit mask for clearing web status. + */ #define PF_CLEAR_WEB 0b11110011 -/** Bit mask for clearing mobile status */ + +/** + * @brief Bit mask for clearing mobile status. + */ #define PF_CLEAR_MOBILE 0b11001111 -/** Bit mask for clearing main status */ + +/** + * @brief Bit mask for clearing main status. + */ #define PF_CLEAR_STATUS 0b00111111 /** * @brief Game types */ enum activity_type : uint8_t { - /// "Playing ..." + /** + * @brief "Playing ..." + */ at_game = 0, - /// "Streaming ..." + + /** + * @brief "Streaming ..." + */ at_streaming = 1, - /// "Listening to..." + + /** + * @brief "Listening to..." + */ at_listening = 2, - /// "Watching..." + + /** + * @brief "Watching..." + */ at_watching = 3, - /// "Emoji..." + + /** + * @brief "Emoji..." + */ at_custom = 4, - /// "Competing in..." + + /** + * @brief "Competing in..." + */ at_competing = 5 }; @@ -118,23 +208,49 @@ enum activity_type : uint8_t { * @brief Activity types for rich presence */ enum activity_flags { - /// In an instance + /** + * @brief In an instance. + */ af_instance = 0b000000001, - /// Joining + + /** + * @brief Joining. + */ af_join = 0b000000010, - /// Spectating + + /** + * @brief Spectating. + */ af_spectate = 0b000000100, - /// Sending join request + + /** + * @brief Sending join request. + */ af_join_request = 0b000001000, - /// Synchronising + + /** + * @brief Synchronising. + */ af_sync = 0b000010000, - /// Playing + + /** + * @brief Playing. + */ af_play = 0b000100000, - /// Party privacy friends + + /** + * @brief Party privacy friends. + */ af_party_privacy_friends = 0b001000000, - /// Party privacy voice channel + + /** + * @brief Party privacy voice channel. + */ af_party_privacy_voice_channel = 0b010000000, - /// Embedded + + /** + * @brief Embedded. + */ af_embedded = 0b100000000 }; @@ -143,10 +259,13 @@ enum activity_flags { */ struct DPP_EXPORT activity_button { public: - /** The text shown on the button (1-32 characters) + /** + * @brief The text shown on the button (1-32 characters). */ std::string label; - /** The url opened when clicking the button (1-512 characters). It's may be empty + + /** + * @brief The url opened when clicking the button (1-512 characters, can be empty). * * @note Bots cannot access the activity button URLs. */ @@ -161,16 +280,23 @@ struct DPP_EXPORT activity_button { */ struct DPP_EXPORT activity_assets { public: - /** The large asset image which usually contain snowflake ID or prefixed image ID + /** + * @brief The large asset image which usually contain snowflake ID or prefixed image ID. */ std::string large_image; - /** Text displayed when hovering over the large image of the activity + + /** + * @brief Text displayed when hovering over the large image of the activity. */ std::string large_text; - /** The small asset image which usually contain snowflake ID or prefixed image ID + + /** + * @brief The small asset image which usually contain snowflake ID or prefixed image ID. */ std::string small_image; - /** Text displayed when hovering over the small image of the activity + + /** + * @brief Text displayed when hovering over the small image of the activity. */ std::string small_text; @@ -179,17 +305,22 @@ struct DPP_EXPORT activity_assets { }; /** - * @brief Secrets for Rich Presence joining and spectating + * @brief Secrets for Rich Presence joining and spectating. */ struct DPP_EXPORT activity_secrets { public: - /** The secret for joining a party + /** + * @brief The secret for joining a party. */ std::string join; - /** The secret for spectating a game + + /** + * @brief The secret for spectating a game. */ std::string spectate; - /** The secret for a specific instanced match + + /** + * @brief The secret for a specific instanced match. */ std::string match; @@ -202,13 +333,20 @@ struct DPP_EXPORT activity_secrets { */ struct DPP_EXPORT activity_party { public: - /** The ID of the party + /** + * @brief The ID of the party. */ snowflake id; - /** The party's current size. Used to show the party's current size + + /** + * @brief The party's current size. + * Used to show the party's current size. */ int32_t current_size; - /** The party's maximum size. Used to show the party's maximum size + + /** + * @brief The party's maximum size. + * Used to show the party's maximum size. */ int32_t maximum_size; @@ -221,56 +359,90 @@ struct DPP_EXPORT activity_party { */ class DPP_EXPORT activity { public: - /** Name of activity - * e.g. "Fortnite" + /** + * @brief Name of activity. + * e.g. "Fortnite", "Mr Boom's Firework Factory", etc. */ std::string name; - /** State of activity or the custom user status. - * e.g. "Waiting in lobby" + + /** + * @brief State of activity or the custom user status. + * e.g. "Waiting in lobby". */ std::string state; - /** What the player is currently doing + + /** + * @brief What the player is currently doing. */ std::string details; - /** Images for the presence and their hover texts + + /** + * @brief Images for the presence and their hover texts. */ activity_assets assets; - /** URL. - * Only applicable for certain sites such a YouTube - * Alias: details + + /** + * @brief URL of activity (this is also named details). + * + * @note Only applicable for certain sites such a YouTube */ std::string url; - /** The custom buttons shown in the Rich Presence (max 2) + + /** + * @brief The custom buttons shown in the Rich Presence (max 2). */ std::vector buttons; - /** The emoji used for the custom status + + /** + * @brief The emoji used for the custom status. */ dpp::emoji emoji; - /** Information of the current party if there is one + + /** + * @brief Information of the current party if there is one. */ activity_party party; - /** Secrets for rich presence joining and spectating + + /** + * @brief Secrets for rich presence joining and spectating. */ activity_secrets secrets; - /** Activity type + + /** + * @brief Activity type. */ activity_type type; - /** Time activity was created + + /** + * @brief Time activity was created. */ time_t created_at; - /** Start time. e.g. when game was started + + /** + * @brief Start time. + * e.g. when game was started. */ time_t start; - /** End time, e.g. for songs on spotify + + /** + * @brief End time. + * e.g. for songs on spotify. */ time_t end; - /** Creating application (e.g. a linked account on the user's client) + + /** + * @brief Creating application. + * e.g. a linked account on the user's client. */ snowflake application_id; - /** Flags bitmask from dpp::activity_flags + + /** + * @brief Flags bitmask from dpp::activity_flags. */ uint8_t flags; - /** Whether or not the activity is an instanced game session + + /** + * @brief Whether or not the activity is an instanced game session. */ bool is_instance; @@ -336,16 +508,26 @@ class DPP_EXPORT presence : public json_interface { virtual json to_json_impl(bool with_id = false) const; public: - /** The user the presence applies to */ - snowflake user_id; + /** + * @brief The user the presence applies to. + */ + snowflake user_id; - /** Guild ID. Apparently, Discord supports this internally but the client doesn't... */ - snowflake guild_id; + /** + * @brief Guild ID. + * + * @note Apparently, Discord supports this internally, but the client doesn't... + */ + snowflake guild_id; - /** Flags bitmask containing dpp::presence_flags */ - uint8_t flags; + /** + * @brief Flags bitmask containing dpp::presence_flags + */ + uint8_t flags; - /** List of activities */ + /** + * @brief List of activities. + */ std::vector activities; /** Constructor */ @@ -371,27 +553,32 @@ class DPP_EXPORT presence : public json_interface { /** Destructor */ ~presence(); - /** The users status on desktop + /** + * @brief The users status on desktop * @return The user's status on desktop */ presence_status desktop_status() const; - /** The user's status on web + /** + * @brief The user's status on web * @return The user's status on web */ presence_status web_status() const; - /** The user's status on mobile + /** + * @brief The user's status on mobile * @return The user's status on mobile */ presence_status mobile_status() const; - /** The user's status as shown to other users + /** + * @brief The user's status as shown to other users * @return The user's status as shown to other users */ presence_status status() const; - /** Build JSON from this object. + /** + * @brief Build JSON from this object. * * @note This excludes any part of the presence object that are not valid for websockets and bots, * and includes websocket opcode 3. You will not get what you expect if you call this on a user's @@ -403,7 +590,9 @@ class DPP_EXPORT presence : public json_interface { json to_json(bool with_id = false) const; // Intentional shadow of json_interface, mostly present for documentation }; -/** A container of presences */ +/** + * @brief A container of presences + */ typedef std::unordered_map presence_map; } // namespace dpp diff --git a/include/dpp/prune.h b/include/dpp/prune.h index 3dc15169af..9952b841f2 100644 --- a/include/dpp/prune.h +++ b/include/dpp/prune.h @@ -48,23 +48,29 @@ struct DPP_EXPORT prune : public json_interface { public: /** - * Destroy this prune object + * @brief Destroy this prune object */ virtual ~prune() = default; - /** Number of days to include in the prune + /** + * @brief Number of days to include in the prune. */ uint32_t days = 0; - /** Roles to include in the prune (empty to include everyone) + + /** + * @brief Roles to include in the prune (empty to include everyone). */ std::vector include_roles; - /** True if the count of pruneable users should be returned - * (discord recommend not using this on big guilds) + + /** + * @brief True if the count of pruneable users should be returned. + * @warning Discord recommend not using this on big guilds. */ bool compute_prune_count; /** - * Build JSON from this object. + * @brief Build JSON from this object. + * * @param with_prune_count True if the prune count boolean is to be set in the built JSON * @return The JSON of the prune object */ diff --git a/include/dpp/queues.h b/include/dpp/queues.h index 232cbe98eb..b3e9b8ec97 100644 --- a/include/dpp/queues.h +++ b/include/dpp/queues.h @@ -37,31 +37,69 @@ namespace dpp { * @brief Error values. Most of these are currently unused in https_client. */ enum http_error { - /// Request successful + /** + * @brief Request successful. + */ h_success = 0, - /// Status unknown + + /** + * @brief Status unknown. + */ h_unknown, - /// Connect failed + + /** + * @brief Connect failed. + */ h_connection, - /// Invalid local ip address + + /** + * @brief Invalid local ip address. + */ h_bind_ip_address, - /// Read error + + /** + * @brief Read error. + */ h_read, - /// Write error + + /** + * @brief Write error. + */ h_write, - /// Too many 30x redirects + + /** + * @brief Too many 30x redirects. + */ h_exceed_redirect_count, - /// Request cancelled + + /** + * @brief Request cancelled. + */ h_canceled, - /// SSL connection error + + /** + * @brief SSL connection error. + */ h_ssl_connection, - /// SSL cert loading error + + /** + * @brief SSL cert loading error. + */ h_ssl_loading_certs, - /// SSL server verification error + + /** + * @brief SSL server verification error. + */ h_ssl_server_verification, - /// Unsupported multipart boundary characters + + /** + * @brief Unsupported multipart boundary characters. + */ h_unsupported_multipart_boundary_chars, - /// Compression error + + /** + * @brief Compression error. + */ h_compression, }; @@ -70,32 +108,67 @@ enum http_error { * rate limit figures, and returned request body. */ struct DPP_EXPORT http_request_completion_t { - /** @brief HTTP headers of response */ + /** + * @brief HTTP headers of response. + */ std::multimap headers; - /** @brief HTTP status, e.g. 200 = OK, 404 = Not found, 429 = Rate limited */ + + /** + * @brief HTTP status. + * e.g. 200 = OK, 404 = Not found, 429 = Rate limited, etc. + */ uint16_t status = 0; - /** @brief Error status (e.g. if the request could not connect at all) */ + + /** + * @brief Error status. + * e.g. if the request could not connect at all. + */ http_error error = h_success; - /** @brief Ratelimit bucket */ + + /** + * @brief Ratelimit bucket. + */ std::string ratelimit_bucket; - /** @brief Ratelimit limit of requests */ + + /** + * @brief Ratelimit limit of requests. + */ uint64_t ratelimit_limit = 0; - /** @brief Ratelimit remaining requests */ + + /** + * @brief Ratelimit remaining requests. + */ uint64_t ratelimit_remaining = 0; - /** @brief Ratelimit reset after (seconds) */ + + /** + * @brief Ratelimit reset after (seconds). + */ uint64_t ratelimit_reset_after = 0; - /** @brief Ratelimit retry after (seconds) */ + + /** + * @brief Ratelimit retry after (seconds). + */ uint64_t ratelimit_retry_after = 0; - /** @brief True if this request has caused us to be globally rate limited */ + + /** + * @brief True if this request has caused us to be globally rate limited. + */ bool ratelimit_global = false; - /** @brief Reply body */ + + /** + * @brief Reply body. + */ std::string body; - /** @brief Ping latency */ + + /** + * @brief Ping latency. + */ double latency; }; /** * @brief Results of HTTP requests are called back to these std::function types. + * * @note Returned http_completion_events are called ASYNCHRONOUSLY in your * code which means they execute in a separate thread. The completion events * arrive in order. @@ -106,15 +179,29 @@ typedef std::function http_completion_ev * @brief Various types of http method supported by the Discord API */ enum http_method { - /// GET + /** + * @brief GET. + */ m_get, - /// POST + + /** + * @brief POST. + */ m_post, - /// PUT + + /** + * @brief PUT. + */ m_put, - /// PATCH + + /** + * @brief PATCH. + */ m_patch, - /// DELETE + + /** + * @brief DELETE. + */ m_delete }; @@ -129,36 +216,81 @@ enum http_method { * request_queue class. */ class DPP_EXPORT http_request { - /** @brief Completion callback */ + /** + * @brief Completion callback. + */ http_completion_event complete_handler; - /** @brief True if request has been made */ + + /** + * @brief True if request has been made. + */ bool completed; - /** @brief True for requests that are not going to discord (rate limits code skipped) */ + + /** + * @brief True for requests that are not going to discord (rate limits code skipped). + */ bool non_discord; public: - /** @brief Endpoint name e.g. /api/users */ + /** + * @brief Endpoint name + * e.g. /api/users. + */ std::string endpoint; - /** @brief Major and minor parameters */ + + /** + * @brief Major and minor parameters. + */ std::string parameters; - /** @brief Postdata for POST and PUT */ + + /** + * @brief Postdata for POST and PUT. + */ std::string postdata; - /** @brief HTTP method for request */ + + /** + * @brief HTTP method for request. + */ http_method method; - /** @brief Audit log reason for Discord requests, if non-empty */ + + /** + * @brief Audit log reason for Discord requests, if non-empty. + */ std::string reason; - /** @brief Upload file name (server side) */ + + /** + * @brief Upload file name (server side). + */ std::vector file_name; - /** @brief Upload file contents (binary) */ + + /** + * @brief Upload file contents (binary). + */ std::vector file_content; - /** @brief Upload file mime types (application/octet-stream if unspecified) */ + + /** + * @brief Upload file mime types. + * application/octet-stream if unspecified. + */ std::vector file_mimetypes; - /** @brief Request mime type */ + + /** + * @brief Request mime type. + */ std::string mimetype; - /** @brief Request headers (non-discord requests only) */ + + /** + * @brief Request headers (non-discord requests only). + */ std::multimap req_headers; - /** @brief Waiting for rate limit to expire */ + + /** + * @brief Waiting for rate limit to expire. + */ bool waiting; - /** @brief HTTP protocol */ + + /** + * @brief HTTP protocol. + */ std::string protocol; /** @@ -229,15 +361,29 @@ class DPP_EXPORT http_request { * each endpoint. */ struct DPP_EXPORT bucket_t { - /** @brief Request limit */ + /** + * @brief Request limit. + */ uint64_t limit; - /** @brief Requests remaining */ + + /** + * @brief Requests remaining. + */ uint64_t remaining; - /** @brief Ratelimit of this bucket resets after this many seconds */ + + /** + * @brief Rate-limit of this bucket resets after this many seconds. + */ uint64_t reset_after; - /** @brief Ratelimit of this bucket can be retried after this many seconds */ + + /** + * @brief Rate-limit of this bucket can be retried after this many seconds. + */ uint64_t retry_after; - /** @brief Timestamp this buckets counters were updated */ + + /** + * @brief Timestamp this buckets counters were updated. + */ time_t timestamp; }; @@ -253,47 +399,47 @@ struct DPP_EXPORT bucket_t { class DPP_EXPORT in_thread { private: /** - * @brief True if ending + * @brief True if ending. */ bool terminating; /** - * @brief Request queue that owns this in_thread + * @brief Request queue that owns this in_thread. */ class request_queue* requests; /** - * @brief The cluster that owns this in_thread + * @brief The cluster that owns this in_thread. */ class cluster* creator; /** - * @brief Inbound queue mutex thread safety + * @brief Inbound queue mutex thread safety. */ std::shared_mutex in_mutex; /** - * @brief Inbound queue thread + * @brief Inbound queue thread. */ std::thread* in_thr; /** - * @brief Inbound queue condition, signalled when there are requests to fulfill + * @brief Inbound queue condition, signalled when there are requests to fulfill. */ std::condition_variable in_ready; /** - * @brief Ratelimit bucket counters + * @brief Rate-limit bucket counters. */ std::map buckets; /** - * @brief Queue of requests to be made + * @brief Queue of requests to be made. */ std::map> requests_in; /** - * @brief Inbound queue thread loop + * @brief Inbound queue thread loop. * @param index Thread index */ void in_loop(uint32_t index); @@ -365,7 +511,8 @@ class DPP_EXPORT request_queue { std::thread* out_thread; /** - * @brief Outbound queue condition, signalled when there are requests completed to call callbacks for + * @brief Outbound queue condition. + * Signalled when there are requests completed to call callbacks for. */ std::condition_variable out_ready; @@ -401,7 +548,9 @@ class DPP_EXPORT request_queue { bool globally_ratelimited; /** - * @brief How many seconds we are globally rate limited for, if globally_ratelimited is true + * @brief How many seconds we are globally rate limited for + * + * @note Only if globally_ratelimited is true. */ uint64_t globally_limited_for; diff --git a/include/dpp/restresults.h b/include/dpp/restresults.h index f38da6de52..ec52ca1b71 100644 --- a/include/dpp/restresults.h +++ b/include/dpp/restresults.h @@ -69,22 +69,34 @@ struct DPP_EXPORT gateway : public json_interface { gateway& fill_from_json_impl(nlohmann::json* j); public: - /// Gateway websocket url + /** + * @brief Gateway websocket url. + */ std::string url; - /// Number of suggested shards to start + /** + * @brief Number of suggested shards to start. + */ uint32_t shards; - /// Total number of sessions that can be started + /** + * @brief Total number of sessions that can be started. + */ uint32_t session_start_total; - /// How many sessions are left + /** + * @brief How many sessions are left. + */ uint32_t session_start_remaining; - /// How many seconds until the session start quota resets + /** + * @brief How many seconds until the session start quota resets. + */ uint32_t session_start_reset_after; - /// How many sessions can be started at the same time + /** + * @brief How many sessions can be started at the same time. + */ uint32_t session_start_max_concurrency; /** @@ -189,18 +201,22 @@ struct DPP_EXPORT error_detail { * @brief Object name which is in error */ std::string object; + /** * @brief Field name which is in error */ std::string field; + /** * @brief Error code */ std::string code; + /** * @brief Error reason (full message) */ std::string reason; + /** * @brief Object field index */ @@ -215,15 +231,18 @@ struct DPP_EXPORT error_info { * @brief Error code */ uint32_t code = 0; + /** * @brief Error message * */ std::string message; + /** * @brief Field specific error descriptions */ std::vector errors; + /** * @brief Human readable error message constructed from the above */ @@ -234,17 +253,23 @@ struct DPP_EXPORT error_info { * @brief The results of a REST call wrapped in a convenient struct */ struct DPP_EXPORT confirmation_callback_t { - /** Information about the HTTP call used to make the request */ + /** + * @brief Information about the HTTP call used to make the request. + */ http_request_completion_t http_info; - /** Value returned, wrapped in variant */ + /** + * @brief Value returned, wrapped in variant. + */ confirmable_t value; - /** Owner/creator of the callback object */ + /** + * @brief Owner/creator of the callback object. + */ const class cluster* bot; /** - * @brief Construct a new confirmation callback t object + * @brief Construct a new confirmation callback t object. */ confirmation_callback_t() = default;