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...

role &	set_name (const std::string &n)
	Set the name of the role Maximum length: 100 Minimum length: 1. More...

role &	set_colour (uint32_t c)
	Set the colour. More...

role &	set_color (uint32_t c)
	Set the color. More...

role &	set_flags (uint8_t f)
	Set the flags. More...

role &	set_integration_id (snowflake i)
	Set the integration id. More...

role &	set_bot_id (snowflake b)
	Set the bot id. More...

role &	set_guild_id (snowflake gid)
	Set the guild id. More...

role &	fill_from_json (nlohmann::json *j)
	Fill this role from json. More...

role &	fill_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...

role &	load_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 the kick members 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

permission	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_id true 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

j	The 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_id	the guild id to place in the json
j	The 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

size	The 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 the kick 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 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_blob	Image binary data
type	Type 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

other Other 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

other Other 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

b	Bot ID to set

Returns: role& reference to self

◆ set_color()

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

Set the color.

Parameters

c	Colour 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

c	Colour 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

f	Flags to set

Returns: role& reference to self

◆ set_guild_id()

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

Set the guild id.

Parameters

gid	Guild ID to set

Returns: role& reference to self

◆ set_integration_id()

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

Set the integration id.

Parameters

i	Integration 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

n	Name to set

Returns: role& reference to self

Exceptions

dpp::exception thrown 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

permission dpp::role::permissions

Role permissions bitmask values from dpp::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

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ role()

◆ ~role()

Member Function Documentation

◆ build_json()

◆ fill_from_json() [1/2]

◆ fill_from_json() [2/2]

◆ get_creation_time()

◆ get_icon_url()

◆ get_members()

◆ get_mention()

◆ has_add_reactions()

◆ has_administrator()

◆ has_attach_files()

◆ has_ban_members()

◆ has_change_nickname()

◆ has_connect()

◆ has_create_instant_invite()

◆ has_create_private_threads()

◆ has_create_public_threads()

◆ has_deafen_members()

◆ has_embed_links()

◆ has_kick_members()

◆ has_manage_channels()

◆ has_manage_emojis_and_stickers()

◆ has_manage_events()

◆ has_manage_guild()

◆ has_manage_messages()

◆ has_manage_nicknames()

◆ has_manage_roles()

◆ has_manage_threads()

◆ has_manage_webhooks()

◆ has_mention_everyone()

◆ has_moderate_members()

◆ has_move_members()

◆ has_mute_members()

◆ has_priority_speaker()

◆ has_read_message_history()

◆ has_request_to_speak()

◆ has_send_messages()

◆ has_send_messages_in_threads()

◆ has_send_tts_messages()

◆ has_speak()

◆ has_stream()

◆ has_use_application_commands()

◆ has_use_embedded_activities()

◆ has_use_external_emojis()

◆ has_use_external_stickers()

◆ has_use_vad()

◆ has_view_audit_log()

◆ has_view_channel()

◆ has_view_guild_insights()

◆ is_hoisted()

◆ is_managed()

◆ is_mentionable()

◆ load_image()

◆ operator!=()

◆ operator==()

◆ set_bot_id()

◆ set_color()

◆ set_colour()

◆ set_flags()

◆ set_guild_id()

◆ set_integration_id()

◆ set_name()

Member Data Documentation

◆ bot_id

◆ colour

◆ flags

◆ guild_id

◆ icon

◆ id

◆ image_data

◆ integration_id

◆ name

◆ permissions

◆ position