Struct serenity::model::Guild

pub struct Guild {
    pub afk_channel_id: Option<ChannelId>,
    pub afk_timeout: u64,
    pub channels: HashMap<ChannelId, Arc<RwLock<GuildChannel>>>,
    pub default_message_notifications: u64,
    pub emojis: HashMap<EmojiId, Emoji>,
    pub features: Vec<Feature>,
    pub icon: Option<String>,
    pub id: GuildId,
    pub joined_at: DateTime<FixedOffset>,
    pub large: bool,
    pub member_count: u64,
    pub members: HashMap<UserId, Member>,
    pub mfa_level: u64,
    pub name: String,
    pub owner_id: UserId,
    pub presences: HashMap<UserId, Presence>,
    pub region: String,
    pub roles: HashMap<RoleId, Role>,
    pub splash: Option<String>,
    pub verification_level: VerificationLevel,
    pub voice_states: HashMap<UserId, VoiceState>,
}

Information about a Discord guild, such as channels, emojis, etc.

Fields

afk_channel_id: Option<ChannelId>

Id of a voice channel that's considered the AFK channel.

afk_timeout: u64

The amount of seconds a user can not show any activity in a voice channel before being moved to an AFK channel -- if one exists.

channels: HashMap<ChannelId, Arc<RwLock<GuildChannel>>>

All voice and text channels contained within a guild.

This contains all channels regardless of permissions (i.e. the ability of the bot to read from or connect to them).

default_message_notifications: u64

Indicator of whether notifications for all messages are enabled by default in the guild.

emojis: HashMap<EmojiId, Emoji>

All of the guild's custom emojis.

features: Vec<Feature>

VIP features enabled for the guild. Can be obtained through the Discord Partnership website.

icon: Option<String>

The hash of the icon used by the guild.

In the client, this appears on the guild list on the left-hand side.

id: GuildId

The unique Id identifying the guild.

This is equivilant to the Id of the default role (@everyone) and also that of the default channel (typically #general).

joined_at: DateTime<FixedOffset>

The date that the current user joined the guild.

large: bool

Indicator of whether the guild is considered "large" by Discord.

member_count: u64

The number of members in the guild.

members: HashMap<UserId, Member>

Users who are members of the guild.

Members might not all be available when the ReadyEvent is received if the [member_count] is greater than the LARGE_THRESHOLD set by the library.

mfa_level: u64

Indicator of whether the guild requires multi-factor authentication for Roles or Users with moderation permissions.

name: String

The name of the guild.

owner_id: UserId

The Id of the User who owns the guild.

presences: HashMap<UserId, Presence>

A mapping of Users' Ids to their current presences.

region: String

The region that the voice servers that the guild uses are located in.

roles: HashMap<RoleId, Role>

A mapping of the guild's roles.

splash: Option<String>

An identifying hash of the guild's splash icon.

If the InviteSplash feature is enabled, this can be used to generate a URL to a splash image.

verification_level: VerificationLevel

Indicator of the current verification level of the guild.

voice_states: HashMap<UserId, VoiceState>

A mapping of of Users to their current voice state.

Methods

impl Guild

fn ban<U: Into<UserId>>(&self, user: U, delete_message_days: u8) -> Result<()>

Ban a User from the guild. All messages by the user within the last given number of days given will be deleted.

Refer to the documentation for Guild::ban for more information.

Note: Requires the Ban Members permission.

Examples

Ban a member and remove all messages they've sent in the last 4 days:

// assumes a `user` and `guild` have already been bound
let _ = guild.ban(user, 4);

Errors

Returns a ModelError::InvalidPermissions if the current user does not have permission to perform bans.

Returns a ModelError::DeleteMessageDaysAmount if the number of days' worth of messages to delete is over the maximum.

fn bans(&self) -> Result<Vec<Ban>>

Retrieves a list of Bans for the guild.

Note: Requires the Ban Members permission.

Errors

If the cache is enabled, returns a ModelError::InvalidPermissions if the current user does not have permission to perform bans.

fn channels(&self) -> Result<HashMap<ChannelId, GuildChannel>>

Gets all of the guild's channels over the REST API.

fn create(
    name: &str,
    region: Region,
    icon: Option<&str>
) -> Result<PartialGuild>

Creates a guild with the data provided.

Only a PartialGuild will be immediately returned, and a full Guild will be received over a Shard.

Note: This endpoint is usually only available for user accounts. Refer to Discord's information for the endpoint here for more information. If you require this as a bot, re-think what you are doing and if it really needs to be doing this.

Examples

Create a guild called "test" in the US West region with no icon:

use serenity::model::{Guild, Region};

let _guild = Guild::create_guild("test", Region::UsWest, None);

fn create_channel(&self, name: &str, kind: ChannelType) -> Result<GuildChannel>

Creates a new Channel in the guild.

Note: Requires the Manage Channels permission.

Examples

use serenity::model::ChannelType;

// assuming a `guild` has already been bound

let _ = guild.create_channel("my-test-channel", ChannelType::Text);

Errors

If the cache is enabled, returns a ModelError::InvalidPermissions if the current user does not have permission to perform bans.

fn create_emoji(&self, name: &str, image: &str) -> Result<Emoji>

Creates an emoji in the guild with a name and base64-encoded image. The utils::read_image function is provided for you as a simple method to read an image and encode it into base64, if you are reading from the filesystem.

The name of the emoji must be at least 2 characters long and can only contain alphanumeric characters and underscores.

Requires the Manage Emojis permission.

Examples

See the EditProfile::avatar example for an in-depth example as to how to read an image from the filesystem and encode it as base64. Most of the example can be applied similarly for this method.

fn create_integration<I>(&self, integration_id: I, kind: &str) -> Result<()> where
    I: Into<IntegrationId>, 

Creates an integration for the guild.

Requires the Manage Guild permission.

fn create_role<F>(&self, f: F) -> Result<Role> where
    F: FnOnce(EditRole) -> EditRole, 

Creates a new role in the guild with the data set, if any.

Note: Requires the Manage Roles permission.

Examples

Create a role which can be mentioned, with the name 'test':

// assuming a `guild` has been bound

let role = guild.create_role(|r| r.hoist(true).name("role"));

Errors

If the cache is enabled, returns a ModelError::InvalidPermissions if the current user does not have permission to perform bans.

fn delete(&self) -> Result<PartialGuild>

Deletes the current guild if the current user is the owner of the guild.

Note: Requires the current user to be the owner of the guild.

Errors

If the cache is enabled, then returns a ModelError::InvalidUser if the current user is not the guild owner.

fn delete_emoji<E: Into<EmojiId>>(&self, emoji_id: E) -> Result<()>

Deletes an Emoji from the guild.

Requires the Manage Emojis permission.

fn delete_integration<I: Into<IntegrationId>>(
    &self,
    integration_id: I
) -> Result<()>

Deletes an integration by Id from the guild.

Requires the Manage Guild permission.

fn delete_role<R: Into<RoleId>>(&self, role_id: R) -> Result<()>

Deletes a Role by Id from the guild.

Also see Role::delete if you have the cache and methods features enabled.

Requires the Manage Roles permission.

fn edit<F>(&mut self, f: F) -> Result<()> where
    F: FnOnce(EditGuild) -> EditGuild, 

Edits the current guild with new data where specified.

Refer to EditGuild's documentation for a full list of methods.

Note: Requires the current user to have the Manage Guild permission.

Examples

Change a guild's icon using a file name "icon.png":

use serenity::utils;

// We are using read_image helper function from utils.
let base64_icon = utils::read_image("./icon.png")
    .expect("Failed to read image");

guild.edit(|g| g.icon(base64_icon));

Errors

If the cache is enabled, returns a ModelError::InvalidPermissions if the current user does not have permission to perform bans.

fn edit_emoji<E: Into<EmojiId>>(&self, emoji_id: E, name: &str) -> Result<Emoji>

Edits an Emoji's name in the guild.

Also see Emoji::edit if you have the cache and methods features enabled.

Requires the Manage Emojis permission.

fn edit_member<F, U>(&self, user_id: U, f: F) -> Result<()> where
    F: FnOnce(EditMember) -> EditMember,
    U: Into<UserId>, 

Edits the properties of member of the guild, such as muting or nicknaming them.

Refer to EditMember's documentation for a full list of methods and permission restrictions.

Examples

Mute a member and set their roles to just one role with a predefined Id:

guild.edit_member(user_id, |m| m.mute(true).roles(&vec![role_id]));

fn edit_nickname(&self, new_nickname: Option<&str>) -> Result<()>

Edits the current user's nickname for the guild.

Pass None to reset the nickname.

Note: Requires the Change Nickname permission.

Errors

If the cache is enabled, returns a ModelError::InvalidPermissions if the current user does not have permission to change their own nickname.

fn edit_role<F, R>(&self, role_id: R, f: F) -> Result<Role> where
    F: FnOnce(EditRole) -> EditRole,
    R: Into<RoleId>, 

Edits a role, optionally setting its fields.

Requires the Manage Roles permission.

Examples

Make a role hoisted:

guild.edit_role(RoleId(7), |r| r.hoist(true));

fn emoji<E: Into<EmojiId>>(&self, emoji_id: E) -> Result<Emoji>

Gets an emoji in the guild by Id.

Requires the Manage Emojis permission.

fn emojis(&self) -> Result<Vec<Emoji>>

Gets a list of all of the guild's emojis.

Requires the Manage Emojis permission.

fn get<G: Into<GuildId>>(guild_id: G) -> Result<PartialGuild>

Gets a partial amount of guild data by its Id.

Requires that the current user be in the guild.

fn icon_url(&self) -> Option<String>

Returns the formatted URL of the guild's icon, if one exists.

fn integrations(&self) -> Result<Vec<Integration>>

Gets all integration of the guild.

This performs a request over the REST API.

fn invites(&self) -> Result<Vec<RichInvite>>

Retrieves the active invites for the guild.

Note: Requires the Manage Guild permission.

Errors

If the cache is enabled, returns a ModelError::InvalidPermissions if the current user does not have permission to perform bans.

fn is_large(&self) -> bool

Checks if the guild is 'large'. A guild is considered large if it has more than 250 members.

fn kick<U: Into<UserId>>(&self, user_id: U) -> Result<()>

Kicks a Member from the guild.

Requires the Kick Members permission.

fn leave(&self) -> Result<()>

Leaves the guild.

fn member<U: Into<UserId>>(&self, user_id: U) -> Result<Member>

Gets a user's Member for the guild by Id.

fn members<U>(
    &self,
    limit: Option<u64>,
    after: Option<U>
) -> Result<Vec<Member>> where
    U: Into<UserId>, 

Gets a list of the guild's members.

Optionally pass in the limit to limit the number of results. Maximum value is 1000. Optionally pass in after to offset the results by a User's Id.

fn member_named(&self, name: &str) -> Option<&Member>

Retrieves the first Member found that matches the name - with an optional discriminator - provided.

Searching with a discriminator given is the most precise form of lookup, as no two people can share the same username and discriminator.

If a member can not be found by username or username#discriminator, then a search will be done for the nickname. When searching by nickname, the hash (#) and everything after it is included in the search.

The following are valid types of searches:

• username: "zey"
• username and discriminator: "zey#5479"
• nickname: "zeyla" or "zeylas#nick"

fn move_member<C, U>(&self, user_id: U, channel_id: C) -> Result<()> where
    C: Into<ChannelId>,
    U: Into<UserId>, 

Moves a member to a specific voice channel.

Requires the Move Members permission.

fn permissions_for<C, U>(&self, channel_id: C, user_id: U) -> Permissions where
    C: Into<ChannelId>,
    U: Into<UserId>, 

Calculate a User's permissions in a given channel in the guild.

fn prune_count(&self, days: u16) -> Result<GuildPrune>

Retrieves the count of the number of Members that would be pruned with the number of given days.

See the documentation on GuildPrune for more information.

Note: Requires the Kick Members permission.

Errors

If the cache is enabled, returns a ModelError::InvalidPermissions if the current user does not have permission to perform bans.

fn shard_id(&self) -> u64

Returns the Id of the shard associated with the guild.

When the cache is enabled this will automatically retrieve the total number of shards.

Note: When the cache is enabled, this function unlocks the cache to retrieve the total number of shards in use. If you already have the total, consider using utils::shard_id.

fn splash_url(&self) -> Option<String>

Returns the formatted URL of the guild's splash image, if one exists.

fn start_integration_sync<I: Into<IntegrationId>>(
    &self,
    integration_id: I
) -> Result<()>

Starts an integration sync for the given integration Id.

Requires the Manage Guild permission.

fn start_prune(&self, days: u16) -> Result<GuildPrune>

Starts a prune of Members.

See the documentation on GuildPrune for more information.

Note: Requires the Kick Members permission.

Errors

If the cache is enabled, returns a ModelError::InvalidPermissions if the current user does not have permission to perform bans.

fn unban<U: Into<UserId>>(&self, user_id: U) -> Result<()>

Unbans the given User from the guild.

Note: Requires the Ban Members permission.

Errors

If the cache is enabled, returns a ModelError::InvalidPermissions if the current user does not have permission to perform bans.

fn webhooks(&self) -> Result<Vec<Webhook>>

Retrieves the guild's webhooks.

Note: Requires the Manage Webhooks permission.

fn get_bans(&self) -> Result<Vec<Ban>>

Deprecated since 0.1.5

: Use bans instead.

Alias of bans.

fn get_channels(&self) -> Result<HashMap<ChannelId, GuildChannel>>

Deprecated since 0.1.5

: Use channels instead.

Alias of channels.

fn get_emoji<E: Into<EmojiId>>(&self, emoji_id: E) -> Result<Emoji>

Deprecated since 0.1.5

: Use emoji instead.

Alias of emoji.

fn get_emojis(&self) -> Result<Vec<Emoji>>

Deprecated since 0.1.5

: Use emojis instead.

Alias of emojis.

fn get_integrations(&self) -> Result<Vec<Integration>>

Deprecated since 0.1.5

: Use integrations instead.

Alias of integrations.

fn get_invites(&self) -> Result<Vec<RichInvite>>

Deprecated since 0.1.5

: Use invites instead.

Alias of invites.

fn get_member<U: Into<UserId>>(&self, user_id: U) -> Result<Member>

Deprecated since 0.1.5

: Use member instead.

Alias of member.

fn get_members<U>(
    &self,
    limit: Option<u64>,
    after: Option<U>
) -> Result<Vec<Member>> where
    U: Into<UserId>, 

Deprecated since 0.1.5

: Use members instead.

Alias of members.

fn get_member_named(&self, name: &str) -> Option<&Member>

Deprecated since 0.1.5

: Use member_named instead.

Alias of member_named.

fn get_prune_count(&self, days: u16) -> Result<GuildPrune>

Deprecated since 0.1.5

: Use prune_count instead.

Alias of prune_count.

fn get_webhooks(&self) -> Result<Vec<Webhook>>

Deprecated since 0.1.5

: Use webhooks instead.

Alias of webhooks.

Trait Implementations

impl Clone for Guild

fn clone(&self) -> Guild

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Guild

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Guild

fn deserialize<D: Deserializer<'de>>(
    deserializer: D
) -> StdResult<Self, D::Error>

Deserialize this value from the given Serde deserializer.