use model::prelude::*; use super::super::utils::{deserialize_emojis, deserialize_roles}; #[cfg(feature = "model")] use builder::{EditGuild, EditMember, EditRole}; /// Partial information about a [`Guild`]. This does not include information /// like member data. /// /// [`Guild`]: struct.Guild.html #[derive(Clone, Debug, Deserialize, Serialize)] pub struct PartialGuild { pub id: GuildId, pub afk_channel_id: Option, pub afk_timeout: u64, pub default_message_notifications: DefaultMessageNotificationLevel, pub embed_channel_id: Option, pub embed_enabled: bool, #[serde(deserialize_with = "deserialize_emojis")] pub emojis: HashMap, /// Features enabled for the guild. /// /// Refer to [`Guild::features`] for more information. /// /// [`Guild::features`]: struct.Guild.html#structfield.features pub features: Vec, pub icon: Option, pub mfa_level: MfaLevel, pub name: String, pub owner_id: UserId, pub region: String, #[serde(deserialize_with = "deserialize_roles")] pub roles: HashMap, pub splash: Option, pub verification_level: VerificationLevel, } #[cfg(feature = "model")] impl PartialGuild { /// Ban a [`User`] from the guild. All messages by the /// user within the last given number of days given will be deleted. This /// may be a range between `0` and `7`. /// /// **Note**: Requires the [Ban Members] permission. /// /// # Examples /// /// Ban a member and remove all messages they've sent in the last 4 days: /// /// ```rust,ignore /// // assumes a `user` and `guild` have already been bound /// let _ = guild.ban(user, 4); /// ``` /// /// # Errors /// /// Returns a [`ModelError::DeleteMessageDaysAmount`] if the number of /// days' worth of messages to delete is over the maximum. /// /// [`ModelError::DeleteMessageDaysAmount`]: /// enum.ModelError.html#variant.DeleteMessageDaysAmount /// [`User`]: struct.User.html /// [Ban Members]: permissions/constant.BAN_MEMBERS.html pub fn ban>(&self, user: U, delete_message_days: u8) -> Result<()> { if delete_message_days > 7 { return Err(Error::Model( ModelError::DeleteMessageDaysAmount(delete_message_days), )); } self.id.ban(user, &delete_message_days) } /// Gets a list of the guild's bans. /// /// Requires the [Ban Members] permission. /// /// [Ban Members]: permissions/constant.BAN_MEMBERS.html #[inline] pub fn bans(&self) -> Result> { self.id.bans() } /// Gets all of the guild's channels over the REST API. /// /// [`Guild`]: struct.Guild.html #[inline] pub fn channels(&self) -> Result> { self.id.channels() } /// Creates a [`GuildChannel`] in the guild. /// /// Refer to [`http::create_channel`] for more information. /// /// Requires the [Manage Channels] permission. /// /// # Examples /// /// Create a voice channel in a guild with the name `test`: /// /// ```rust,ignore /// use serenity::model::ChannelType; /// /// guild.create_channel("test", ChannelType::Voice, None); /// ``` /// /// [`GuildChannel`]: struct.GuildChannel.html /// [`http::create_channel`]: ../http/fn.create_channel.html /// [Manage Channels]: permissions/constant.MANAGE_CHANNELS.html #[inline] pub fn create_channel(&self, name: &str, kind: ChannelType, category: C) -> Result where C: Into> { self.id.create_channel(name, kind, category) } /// Creates an emoji in the guild with a name and base64-encoded image. /// /// Refer to the documentation for [`Guild::create_emoji`] for more /// information. /// /// 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. /// /// [`EditProfile::avatar`]: ../builder/struct.EditProfile.html#method.avatar /// [`Guild::create_emoji`]: struct.Guild.html#method.create_emoji /// [`utils::read_image`]: ../utils/fn.read_image.html /// [Manage Emojis]: permissions/constant.MANAGE_EMOJIS.html #[inline] pub fn create_emoji(&self, name: &str, image: &str) -> Result { self.id.create_emoji(name, image) } /// Creates an integration for the guild. /// /// Requires the [Manage Guild] permission. /// /// [Manage Guild]: permissions/constant.MANAGE_GUILD.html #[inline] pub fn create_integration(&self, integration_id: I, kind: &str) -> Result<()> where I: Into { self.id.create_integration(integration_id, kind) } /// Creates a new role in the guild with the data set, if any. /// /// See the documentation for [`Guild::create_role`] on how to use this. /// /// **Note**: Requires the [Manage Roles] permission. /// /// # Errors /// /// If the `cache` is enabled, returns a [`ModelError::InvalidPermissions`] /// if the current user does not have permission to perform bans. /// /// [`ModelError::InvalidPermissions`]: enum.ModelError.html#variant.InvalidPermissions /// [`Guild::create_role`]: struct.Guild.html#method.create_role /// [Manage Roles]: permissions/constant.MANAGE_ROLES.html #[inline] pub fn create_role EditRole>(&self, f: F) -> Result { self.id.create_role(f) } /// 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. #[inline] pub fn delete(&self) -> Result { self.id.delete() } /// Deletes an [`Emoji`] from the guild. /// /// Requires the [Manage Emojis] permission. /// /// [`Emoji`]: struct.Emoji.html /// [Manage Emojis]: permissions/constant.MANAGE_EMOJIS.html #[inline] pub fn delete_emoji>(&self, emoji_id: E) -> Result<()> { self.id.delete_emoji(emoji_id) } /// Deletes an integration by Id from the guild. /// /// Requires the [Manage Guild] permission. /// /// [Manage Guild]: permissions/constant.MANAGE_GUILD.html #[inline] pub fn delete_integration>(&self, integration_id: I) -> Result<()> { self.id.delete_integration(integration_id) } /// 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. /// /// [`Role`]: struct.Role.html /// [`Role::delete`]: struct.Role.html#method.delete /// [Manage Roles]: permissions/constant.MANAGE_ROLES.html #[inline] pub fn delete_role>(&self, role_id: R) -> Result<()> { self.id.delete_role(role_id) } /// Edits the current guild with new data where specified. /// /// **Note**: Requires the current user to have the [Manage Guild] /// permission. /// /// [Manage Guild]: permissions/constant.MANAGE_GUILD.html pub fn edit(&mut self, f: F) -> Result<()> where F: FnOnce(EditGuild) -> EditGuild { match self.id.edit(f) { Ok(guild) => { self.afk_channel_id = guild.afk_channel_id; self.afk_timeout = guild.afk_timeout; self.default_message_notifications = guild.default_message_notifications; self.emojis = guild.emojis; self.features = guild.features; self.icon = guild.icon; self.mfa_level = guild.mfa_level; self.name = guild.name; self.owner_id = guild.owner_id; self.region = guild.region; self.roles = guild.roles; self.splash = guild.splash; self.verification_level = guild.verification_level; Ok(()) }, Err(why) => Err(why), } } /// 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. /// /// [`Emoji`]: struct.Emoji.html /// [`Emoji::edit`]: struct.Emoji.html#method.edit /// [Manage Emojis]: permissions/constant.MANAGE_EMOJIS.html #[inline] pub fn edit_emoji>(&self, emoji_id: E, name: &str) -> Result { self.id.edit_emoji(emoji_id, name) } /// 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: /// /// ```rust,ignore /// use serenity::model::GuildId; /// /// GuildId(7).edit_member(user_id, |m| m.mute(true).roles(&vec![role_id])); /// ``` #[inline] pub fn edit_member(&self, user_id: U, f: F) -> Result<()> where F: FnOnce(EditMember) -> EditMember, U: Into { self.id.edit_member(user_id, f) } /// 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. /// /// [`ModelError::InvalidPermissions`]: enum.ModelError.html#variant.InvalidPermissions /// [Change Nickname]: permissions/constant.CHANGE_NICKNAME.html #[inline] pub fn edit_nickname(&self, new_nickname: Option<&str>) -> Result<()> { self.id.edit_nickname(new_nickname) } /// Gets a partial amount of guild data by its Id. /// /// Requires that the current user be in the guild. #[inline] pub fn get>(guild_id: G) -> Result { guild_id.into().get() } /// Kicks a [`Member`] from the guild. /// /// Requires the [Kick Members] permission. /// /// [`Member`]: struct.Member.html /// [Kick Members]: permissions/constant.KICK_MEMBERS.html #[inline] pub fn kick>(&self, user_id: U) -> Result<()> { self.id.kick(user_id) } /// Returns a formatted URL of the guild's icon, if the guild has an icon. pub fn icon_url(&self) -> Option { self.icon .as_ref() .map(|icon| format!(cdn!("/icons/{}/{}.webp"), self.id, icon)) } /// Gets all integration of the guild. /// /// This performs a request over the REST API. #[inline] pub fn integrations(&self) -> Result> { self.id.integrations() } /// Gets all of the guild's invites. /// /// Requires the [Manage Guild] permission. /// /// [Manage Guild]: permissions/constant.MANAGE_GUILD.html #[inline] pub fn invites(&self) -> Result> { self.id.invites() } /// Leaves the guild. #[inline] pub fn leave(&self) -> Result<()> { self.id.leave() } /// Gets a user's [`Member`] for the guild by Id. /// /// [`Guild`]: struct.Guild.html /// [`Member`]: struct.Member.html pub fn member>(&self, user_id: U) -> Result { self.id.member(user_id) } /// 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. /// /// [`User`]: struct.User.html pub fn members(&self, limit: Option, after: Option) -> Result> where U: Into { self.id.members(limit, after) } /// Moves a member to a specific voice channel. /// /// Requires the [Move Members] permission. /// /// [Move Members]: permissions/constant.MOVE_MEMBERS.html #[inline] pub fn move_member(&self, user_id: U, channel_id: C) -> Result<()> where C: Into, U: Into { self.id.move_member(user_id, channel_id) } /// Gets the number of [`Member`]s that would be pruned with the given /// number of days. /// /// Requires the [Kick Members] permission. /// /// [`Member`]: struct.Member.html /// [Kick Members]: permissions/constant.KICK_MEMBERS.html #[inline] pub fn prune_count(&self, days: u16) -> Result { self.id.prune_count(days) } /// 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`]. /// /// [`utils::shard_id`]: ../utils/fn.shard_id.html #[cfg(all(feature = "cache", feature = "utils"))] #[inline] pub fn shard_id(&self) -> u64 { self.id.shard_id() } /// Returns the Id of the shard associated with the guild. /// /// When the cache is enabled this will automatically retrieve the total /// number of shards. /// /// When the cache is not enabled, the total number of shards being used /// will need to be passed. /// /// # Examples /// /// Retrieve the Id of the shard for a guild with Id `81384788765712384`, /// using 17 shards: /// /// ```rust,ignore /// use serenity::utils; /// /// // assumes a `guild` has already been bound /// /// assert_eq!(guild.shard_id(17), 7); /// ``` #[cfg(all(feature = "utils", not(feature = "cache")))] #[inline] pub fn shard_id(&self, shard_count: u64) -> u64 { self.id.shard_id(shard_count) } /// Returns the formatted URL of the guild's splash image, if one exists. pub fn splash_url(&self) -> Option { self.icon .as_ref() .map(|icon| format!(cdn!("/splashes/{}/{}.webp"), self.id, icon)) } /// Starts an integration sync for the given integration Id. /// /// Requires the [Manage Guild] permission. /// /// [Manage Guild]: permissions/constant.MANAGE_GUILD.html #[inline] pub fn start_integration_sync>(&self, integration_id: I) -> Result<()> { self.id.start_integration_sync(integration_id) } /// Unbans a [`User`] from the guild. /// /// Requires the [Ban Members] permission. /// /// [`User`]: struct.User.html /// [Ban Members]: permissions/constant.BAN_MEMBERS.html #[inline] pub fn unban>(&self, user_id: U) -> Result<()> { self.id.unban(user_id) } /// Retrieve's the guild's vanity URL. /// /// **Note**: Requires the [Manage Guild] permission. /// /// [Manage Guild]: permissions/constant.MANAGE_GUILD.html #[inline] pub fn vanity_url(&self) -> Result { self.id.vanity_url() } /// Retrieves the guild's webhooks. /// /// **Note**: Requires the [Manage Webhooks] permission. /// /// [Manage Webhooks]: permissions/constant.MANAGE_WEBHOOKS.html #[inline] pub fn webhooks(&self) -> Result> { self.id.webhooks() } /// Obtain a reference to a role by its name. /// /// **Note**: If two or more roles have the same name, obtained reference will be one of /// them. /// /// # Examples /// /// Obtain a reference to a [`Role`] by its name. /// /// ```rust,no_run /// use serenity::model::prelude::*; /// use serenity::prelude::*; /// /// struct Handler; /// /// use serenity::CACHE; /// /// impl EventHandler for Handler { /// fn message(&self, _: Context, msg: Message) { /// let guild = msg.guild_id().unwrap().get().unwrap(); /// let possible_role = guild.role_by_name("role_name"); /// /// if let Some(role) = possible_role { /// println!("Obtained role's reference: {:?}", role); /// } /// } /// } /// /// let mut client = Client::new("token", Handler).unwrap(); /// /// client.start().unwrap(); /// ``` pub fn role_by_name(&self, role_name: &str) -> Option<&Role> { self.roles.values().find(|role| role_name == role.name) } }