D++ (DPP)
C++ Discord API Bot Library
dpp::role Class Reference

Represents a role within a dpp::guild. Roles are combined via logical OR of the permission bitmasks, then channel-specific overrides can be applied on top, deny types apply a logic NOT to the bit mask, and allows apply a logical OR. More...

#include <role.h>

+ Inheritance diagram for dpp::role:
+ Collaboration diagram for dpp::role:

Public Member Functions

 role ()
 Construct a new role object. More...
 
virtual ~role ()
 Destroy the role object. More...
 
roleset_name (const std::string &n)
 Set the name of the role Maximum length: 100 Minimum length: 1. More...
 
roleset_colour (uint32_t c)
 Set the colour. More...
 
roleset_color (uint32_t c)
 Set the color. More...
 
roleset_flags (uint8_t f)
 Set the flags. More...
 
roleset_integration_id (snowflake i)
 Set the integration id. More...
 
roleset_bot_id (snowflake b)
 Set the bot id. More...
 
roleset_guild_id (snowflake gid)
 Set the guild id. More...
 
rolefill_from_json (nlohmann::json *j)
 Fill this role from json. More...
 
rolefill_from_json (snowflake guild_id, nlohmann::json *j)
 Fill this role from json. More...
 
virtual std::string build_json (bool with_id=false) const
 Build a json string from this object. More...
 
std::string get_mention () const
 Get the mention/ping for the role. More...
 
std::string get_icon_url (uint16_t size=0) const
 Returns the role's icon if they have one, otherwise returns an empty string. More...
 
roleload_image (const std::string &image_blob, const image_type type)
 Load an image into the object as base64. More...
 
bool is_hoisted () const
 True if the role is hoisted. More...
 
bool is_mentionable () const
 True if the role is mentionable. More...
 
bool is_managed () const
 True if the role is managed (belongs to a bot or application) More...
 
bool has_create_instant_invite () const
 True if has create instant invite permission. More...
 
bool has_kick_members () const
 True if has create instant invite permission. More...
 
bool has_ban_members () const
 True if has the ban members permission. More...
 
bool has_administrator () const
 True if has the administrator permission. More...
 
bool has_manage_channels () const
 True if has the manage channels permission. More...
 
bool has_manage_guild () const
 True if has the manage guild permission. More...
 
bool has_add_reactions () const
 True if has the add reactions permission. More...
 
bool has_view_audit_log () const
 True if has the view audit log permission. More...
 
bool has_priority_speaker () const
 True if has the priority speaker permission. More...
 
bool has_stream () const
 True if has the stream permission. More...
 
bool has_view_channel () const
 True if has the view channel permission. More...
 
bool has_send_messages () const
 True if has the send messages permission. More...
 
bool has_send_tts_messages () const
 True if has the send TTS messages permission. More...
 
bool has_manage_messages () const
 True if has the manage messages permission. More...
 
bool has_embed_links () const
 True if has the embed links permission. More...
 
bool has_attach_files () const
 True if has the attach files permission. More...
 
bool has_read_message_history () const
 True if has the read message history permission. More...
 
bool has_mention_everyone () const
 True if has the mention @everyone and @here permission. More...
 
bool has_use_external_emojis () const
 True if has the use external emojis permission. More...
 
bool has_view_guild_insights () const
 True if has the view guild insights permission. More...
 
bool has_connect () const
 True if has the connect voice permission. More...
 
bool has_speak () const
 True if has the speak permission. More...
 
bool has_mute_members () const
 True if has the mute members permission. More...
 
bool has_deafen_members () const
 True if has the deafen members permission. More...
 
bool has_move_members () const
 True if has the move members permission. More...
 
bool has_use_vad () const
 
bool has_change_nickname () const
 True if has the change nickname permission. More...
 
bool has_manage_nicknames () const
 True if has the manage nicknames permission. More...
 
bool has_manage_roles () const
 True if has the manage roles permission. More...
 
bool has_manage_webhooks () const
 True if has the manage webhooks permission. More...
 
bool has_manage_emojis_and_stickers () const
 True if has the manage emojis and stickers permission. More...
 
bool has_use_application_commands () const
 True if has the use application commands permission. More...
 
bool has_request_to_speak () const
 True if has the request to speak permission. More...
 
bool has_manage_threads () const
 True if has the manage threads permission. More...
 
bool has_create_public_threads () const
 True if has the create public threads permission. More...
 
bool has_create_private_threads () const
 True if has the create private threads permission. More...
 
bool has_use_external_stickers () const
 True if has the use external stickers permission. More...
 
bool has_send_messages_in_threads () const
 True if has the send messages in threads permission. More...
 
bool has_use_embedded_activities () const
 True if has the start embedded activities permission. More...
 
bool has_manage_events () const
 True if has the manage events permission. More...
 
bool has_moderate_members () const
 True if has the moderate users permission. More...
 
members_container get_members () const
 Get guild members who have this role. More...
 
double get_creation_time () const
 Get the creation time of this object according to Discord. More...
 
bool operator== (const managed &other) const noexcept
 Comparison operator for comparing two managed objects by id. More...
 
bool operator!= (const managed &other) const noexcept
 Comparison operator for comparing two managed objects by id. More...
 

Public Attributes

std::string name
 Role name Between 1 and 100 characters. More...
 
snowflake guild_id
 Guild ID. More...
 
uint32_t colour
 Role colour. A colour of 0 means no colour. If you want a black role, you must use the value 0x000001. More...
 
uint8_t position
 
uint64_t permissions
 
uint8_t flags
 
snowflake integration_id
 
snowflake bot_id
 
std::string unicode_emoji
 
utility::iconhash icon
 
std::string * image_data
 
snowflake id
 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. More...
 

Detailed Description

Represents a role within a dpp::guild. Roles are combined via logical OR of the permission bitmasks, then channel-specific overrides can be applied on top, deny types apply a logic NOT to the bit mask, and allows apply a logical OR.

Note
Every guild has at least one role, called the 'everyone' role, which always has the same role ID as the guild's ID. This is the base permission set applied to all users where no other role or override applies, and is the starting value of the bit mask looped through to calculate channel permissions.

Constructor & Destructor Documentation

◆ role()

dpp::role::role ( )

Construct a new role object.

◆ ~role()

virtual dpp::role::~role ( )
virtual

Destroy the role object.

Member Function Documentation

◆ build_json()

virtual std::string dpp::role::build_json ( bool  with_id = false) const
virtual

Build a json string from this object.

Parameters
with_idtrue if the ID is to be included in the json text
Returns
The json of the role

Reimplemented from dpp::json_interface< role >.

◆ fill_from_json() [1/2]

role & dpp::role::fill_from_json ( nlohmann::json *  j)

Fill this role from json.

Parameters
jThe json data
Returns
A reference to self

◆ fill_from_json() [2/2]

role & dpp::role::fill_from_json ( snowflake  guild_id,
nlohmann::json *  j 
)

Fill this role from json.

Parameters
guild_idthe guild id to place in the json
jThe json data
Returns
A reference to self

◆ get_creation_time()

double dpp::managed::get_creation_time ( ) const
inherited

Get the creation time of this object according to Discord.

Returns
double creation time inferred from the snowflake ID. The minimum possible value is the first second of 2015.

◆ get_icon_url()

std::string dpp::role::get_icon_url ( uint16_t  size = 0) const

Returns the role's icon if they have one, otherwise returns an empty string.

Parameters
sizeThe size of the icon in pixels. It can be any power of two between 16 and 4096. If not specified, the default sized icon is returned.
Returns
std::string icon url or empty string

◆ get_members()

members_container dpp::role::get_members ( ) const

Get guild members who have this role.

Note
This method requires user/members cache to be active
Returns
members_container List of members who have this role

◆ get_mention()

std::string dpp::role::get_mention ( ) const

Get the mention/ping for the role.

Returns
std::string mention

◆ has_add_reactions()

bool dpp::role::has_add_reactions ( ) const

True if has the add reactions permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the add reactions permission or is administrator.

◆ has_administrator()

bool dpp::role::has_administrator ( ) const

True if has the administrator permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the administrator permission or is administrator.

◆ has_attach_files()

bool dpp::role::has_attach_files ( ) const

True if has the attach files permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the attach files permission or is administrator.

◆ has_ban_members()

bool dpp::role::has_ban_members ( ) const

True if has the ban members permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the ban members permission or is administrator.

◆ has_change_nickname()

bool dpp::role::has_change_nickname ( ) const

True if has the change nickname permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the change nickname permission or is administrator.

◆ has_connect()

bool dpp::role::has_connect ( ) const

True if has the connect voice permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the connect voice permission or is administrator.

◆ has_create_instant_invite()

bool dpp::role::has_create_instant_invite ( ) const

True if has create instant invite permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the instant invite permission or is administrator.

◆ has_create_private_threads()

bool dpp::role::has_create_private_threads ( ) const

True if has the create private threads permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the create private threads permission or is administrator.

◆ has_create_public_threads()

bool dpp::role::has_create_public_threads ( ) const

True if has the create public threads permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the create public threads permission or is administrator.

◆ has_deafen_members()

bool dpp::role::has_deafen_members ( ) const

True if has the deafen members permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the deafen members permission or is administrator.

◆ has_embed_links()

bool dpp::role::has_embed_links ( ) const

True if has the embed links permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the embed links permission or is administrator.

◆ has_kick_members()

bool dpp::role::has_kick_members ( ) const

True if has create instant invite permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the kick members permission or is administrator.

◆ has_manage_channels()

bool dpp::role::has_manage_channels ( ) const

True if has the manage channels permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the manage channels permission or is administrator.

◆ has_manage_emojis_and_stickers()

bool dpp::role::has_manage_emojis_and_stickers ( ) const

True if has the manage emojis and stickers permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the manage emojis and stickers permission or is administrator.

◆ has_manage_events()

bool dpp::role::has_manage_events ( ) const

True if has the manage events permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the manage events permission or is administrator.

◆ has_manage_guild()

bool dpp::role::has_manage_guild ( ) const

True if has the manage guild permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the manage guild permission or is administrator.

◆ has_manage_messages()

bool dpp::role::has_manage_messages ( ) const

True if has the manage messages permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the manage messages permission or is administrator.

◆ has_manage_nicknames()

bool dpp::role::has_manage_nicknames ( ) const

True if has the manage nicknames permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the manage nicknames permission or is administrator.

◆ has_manage_roles()

bool dpp::role::has_manage_roles ( ) const

True if has the manage roles permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the manage roles permission or is administrator.

◆ has_manage_threads()

bool dpp::role::has_manage_threads ( ) const

True if has the manage threads permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the manage threads permission or is administrator.

◆ has_manage_webhooks()

bool dpp::role::has_manage_webhooks ( ) const

True if has the manage webhooks permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the manage webhooks permission or is administrator.

◆ has_mention_everyone()

bool dpp::role::has_mention_everyone ( ) const

True if has the mention @everyone and @here permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the mention @everyone and @here permission or is administrator.

◆ has_moderate_members()

bool dpp::role::has_moderate_members ( ) const

True if has the moderate users permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the moderate users permission or is administrator.

◆ has_move_members()

bool dpp::role::has_move_members ( ) const

True if has the move members permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the move members permission or is administrator.

◆ has_mute_members()

bool dpp::role::has_mute_members ( ) const

True if has the mute members permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the mute members permission or is administrator.

◆ has_priority_speaker()

bool dpp::role::has_priority_speaker ( ) const

True if has the priority speaker permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the priority speaker permission or is administrator.

◆ has_read_message_history()

bool dpp::role::has_read_message_history ( ) const

True if has the read message history permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the read message history permission or is administrator.

◆ has_request_to_speak()

bool dpp::role::has_request_to_speak ( ) const

True if has the request to speak permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the request to speak permission or is administrator.

◆ has_send_messages()

bool dpp::role::has_send_messages ( ) const

True if has the send messages permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the send messages permission or is administrator.

◆ has_send_messages_in_threads()

bool dpp::role::has_send_messages_in_threads ( ) const

True if has the send messages in threads permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the send messages in threads permission or is administrator.

◆ has_send_tts_messages()

bool dpp::role::has_send_tts_messages ( ) const

True if has the send TTS messages permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the send TTS messages permission or is administrator.

◆ has_speak()

bool dpp::role::has_speak ( ) const

True if has the speak permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the speak permission or is administrator.

◆ has_stream()

bool dpp::role::has_stream ( ) const

True if has the stream permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the stream permission or is administrator.

◆ has_use_application_commands()

bool dpp::role::has_use_application_commands ( ) const

True if has the use application commands permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the use application commands permission or is administrator.

◆ has_use_embedded_activities()

bool dpp::role::has_use_embedded_activities ( ) const

True if has the start embedded activities permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the start embedded activities permission or is administrator.

◆ has_use_external_emojis()

bool dpp::role::has_use_external_emojis ( ) const

True if has the use external emojis permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the use external emojis permission or is administrator.

◆ has_use_external_stickers()

bool dpp::role::has_use_external_stickers ( ) const

True if has the use external stickers permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the use external stickers permission or is administrator.

◆ has_use_vad()

bool dpp::role::has_use_vad ( ) const

True if has use voice activity detection permission

◆ has_view_audit_log()

bool dpp::role::has_view_audit_log ( ) const

True if has the view audit log permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the view audit log permission or is administrator.

◆ has_view_channel()

bool dpp::role::has_view_channel ( ) const

True if has the view channel permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the view channel permission or is administrator.

◆ has_view_guild_insights()

bool dpp::role::has_view_guild_insights ( ) const

True if has the view guild insights permission.

Note
Having the administrator permission causes this method to always return true Channel specific overrides may apply to permissions.
Returns
bool True if user has the view guild insights permission or is administrator.

◆ is_hoisted()

bool dpp::role::is_hoisted ( ) const

True if the role is hoisted.

Returns
bool Role appears separated from others in the member list

◆ is_managed()

bool dpp::role::is_managed ( ) const

True if the role is managed (belongs to a bot or application)

Returns
bool True if the role is managed (introduced for a bot or other application by Discord)

◆ is_mentionable()

bool dpp::role::is_mentionable ( ) const

True if the role is mentionable.

Returns
bool Role is mentionable

◆ load_image()

role & dpp::role::load_image ( const std::string &  image_blob,
const image_type  type 
)

Load an image into the object as base64.

Parameters
image_blobImage binary data
typeType of image
Returns
emoji& Reference to self

◆ operator!=()

bool dpp::managed::operator!= ( const managed other) const
noexceptinherited

Comparison operator for comparing two managed objects by id.

Parameters
otherOther object to compare against
Returns
true objects are not the same id
false objects are the same id

◆ operator==()

bool dpp::managed::operator== ( const managed other) const
noexceptinherited

Comparison operator for comparing two managed objects by id.

Parameters
otherOther object to compare against
Returns
true objects are the same id
false objects are not the same id

◆ set_bot_id()

role & dpp::role::set_bot_id ( snowflake  b)

Set the bot id.

Parameters
bBot ID to set
Returns
role& reference to self

◆ set_color()

role & dpp::role::set_color ( uint32_t  c)

Set the color.

Parameters
cColour to set
Note
This is an alias of role::set_colour for American spelling.
Returns
role& reference to self

◆ set_colour()

role & dpp::role::set_colour ( uint32_t  c)

Set the colour.

Parameters
cColour to set
Note
There is an americanised version of this method, role::set_color().
Returns
role& reference to self

◆ set_flags()

role & dpp::role::set_flags ( uint8_t  f)

Set the flags.

Parameters
fFlags to set
Returns
role& reference to self

◆ set_guild_id()

role & dpp::role::set_guild_id ( snowflake  gid)

Set the guild id.

Parameters
gidGuild ID to set
Returns
role& reference to self

◆ set_integration_id()

role & dpp::role::set_integration_id ( snowflake  i)

Set the integration id.

Parameters
iIntegration ID to set
Returns
role& reference to self

◆ set_name()

role & dpp::role::set_name ( const std::string &  n)

Set the name of the role Maximum length: 100 Minimum length: 1.

Parameters
nName to set
Returns
role& reference to self
Exceptions
dpp::exceptionthrown if role length is less than 1 character

Member Data Documentation

◆ bot_id

snowflake dpp::role::bot_id

Bot id if any (e.g. role is a bot's role created when it was invited)

◆ colour

uint32_t dpp::role::colour

Role colour. A colour of 0 means no colour. If you want a black role, you must use the value 0x000001.

◆ flags

uint8_t dpp::role::flags

Role flags from dpp::role_flags

◆ guild_id

snowflake dpp::role::guild_id

Guild ID.

◆ icon

utility::iconhash dpp::role::icon

The role icon hash, can be an empty string

◆ id

snowflake dpp::managed::id
inherited

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.

◆ image_data

std::string* dpp::role::image_data

Image data for the role icon (if any)

◆ integration_id

snowflake dpp::role::integration_id

Integration id if any (e.g. role is a bot's role created when it was invited)

◆ name

std::string dpp::role::name

Role name Between 1 and 100 characters.

◆ permissions

uint64_t dpp::role::permissions

Role permissions bitmask values from dpp::role_permissions

◆ position

uint8_t dpp::role::position

Role position

◆ unicode_emoji

std::string dpp::role::unicode_emoji

The unicode emoji used for the role's icon, can be an empty string

D++ Library version 10.0.30D++ Library version 10.0.29D++ Library version 10.0.28D++ Library version 10.0.27D++ Library version 10.0.26D++ Library version 10.0.25D++ Library version 10.0.24D++ Library version 10.0.23D++ Library version 10.0.22D++ Library version 10.0.21D++ Library version 10.0.20D++ Library version 10.0.19D++ Library version 10.0.18D++ Library version 10.0.17D++ Library version 10.0.16D++ Library version 10.0.15D++ Library version 10.0.14D++ Library version 10.0.13D++ Library version 10.0.12D++ Library version 10.0.11D++ Library version 10.0.10D++ Library version 10.0.9D++ Library version 10.0.8D++ Library version 10.0.7D++ Library version 10.0.6D++ Library version 10.0.5D++ Library version 10.0.4D++ Library version 10.0.3D++ Library version 10.0.2D++ Library version 10.0.1D++ Library version 10.0.0D++ Library version 9.0.19D++ Library version 9.0.18D++ Library version 9.0.17D++ Library version 9.0.16D++ Library version 9.0.15D++ Library version 9.0.14D++ Library version 9.0.13D++ Library version 9.0.12D++ Library version 9.0.11D++ Library version 9.0.10D++ Library version 9.0.9D++ Library version 9.0.8D++ Library version 9.0.7D++ Library version 9.0.6D++ Library version 9.0.5D++ Library version 9.0.4D++ Library version 9.0.3D++ Library version 9.0.2D++ Library version 9.0.1D++ Library version 9.0.0D++ Library version 1.0.2D++ Library version 1.0.1D++ Library version 1.0.0