Struct serenity::model::GuildChannel

pub struct GuildChannel {
    pub id: ChannelId,
    pub bitrate: Option<u64>,
    pub category_id: Option<ChannelId>,
    pub guild_id: GuildId,
    pub kind: ChannelType,
    pub last_message_id: Option<MessageId>,
    pub last_pin_timestamp: Option<DateTime<FixedOffset>>,
    pub name: String,
    pub permission_overwrites: Vec<PermissionOverwrite>,
    pub position: i64,
    pub topic: Option<String>,
    pub user_limit: Option<u64>,
    pub nsfw: bool,
}

Represents a guild's text or voice channel. Some methods are available only for voice channels and some are only available for text channels.

Fields

id: ChannelId

The unique Id of the channel.

The default channel Id shares the Id of the guild and the default role.

bitrate: Option<u64>

The bitrate of the channel.

Note: This is only available for voice channels.

category_id: Option<ChannelId>

Whether this guild channel belongs in a category.

guild_id: GuildId

The Id of the guild the channel is located in.

If this matches with the [id], then this is the default text channel.

The original voice channel has an Id equal to the guild's Id, incremented by one.

kind: ChannelType

The type of the channel.

last_message_id: Option<MessageId>

The Id of the last message sent in the channel.

Note: This is only available for text channels.

last_pin_timestamp: Option<DateTime<FixedOffset>>

The timestamp of the time a pin was most recently made.

Note: This is only available for text channels.

name: String

The name of the channel.

permission_overwrites: Vec<PermissionOverwrite>

Permission overwrites for Members and for Roles.

position: i64

The position of the channel.

The default text channel will almost always have a position of -1 or 0.

topic: Option<String>

The topic of the channel.

Note: This is only available for text channels.

user_limit: Option<u64>

The maximum number of members allowed in the channel.

Note: This is only available for voice channels.

nsfw: bool

Used to tell if the channel is not safe for work. Note however, it's recommended to use is_nsfw as it's gonna be more accurate.

Methods

impl GuildChannel

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

Broadcasts to the channel that the current user is typing.

For bots, this is a good indicator for long-running commands.

Note: Requires the Send Messages permission.

Errors

Returns a ModelError::InvalidPermissions if the current user does not have the required permissions.

fn create_invite<F>(&self, f: F) -> Result<RichInvite> where
    F: FnOnce(CreateInvite) -> CreateInvite, 

Creates an invite leading to the given channel.

Examples

Create an invite that can only be used 5 times:

let invite = channel.create_invite(|i| i.max_uses(5));

fn create_permission(&self, target: &PermissionOverwrite) -> Result<()>

Creates a permission overwrite for either a single Member or Role within a Channel.

Refer to the documentation for PermissionOverwrites for more information.

Requires the Manage Channels permission.

Examples

Creating a permission overwrite for a member by specifying the PermissionOverwrite::Member variant, allowing it the Send Messages permission, but denying the Send TTS Messages and Attach Files permissions:

use serenity::model::{
    ModelError,
    PermissionOverwrite,
    PermissionOverwriteType,
    permissions,
};
use serenity::CACHE;

let allow = Permissions::SEND_MESSAGES;
let deny = Permissions::SEND_TTS_MESSAGES | Permissions::ATTACH_FILES;
let overwrite = PermissionOverwrite {
    allow: allow,
    deny: deny,
    kind: PermissionOverwriteType::Member(user_id),
};

let cache = CACHE.read().unwrap();
let channel = cache
    .guild_channel(channel_id)
    .ok_or(ModelError::ItemMissing)?;

channel.read().unwrap().create_permission(&overwrite)?;

Creating a permission overwrite for a role by specifying the PermissionOverwrite::Role variant, allowing it the Manage Webhooks permission, but denying the Send TTS Messages and Attach Files permissions:

use serenity::model::{
    ModelError,
    PermissionOverwrite,
    PermissionOverwriteType,
    permissions,
};
use serenity::CACHE;

let allow = Permissions::SEND_MESSAGES;
let deny = Permissions::SEND_TTS_MESSAGES | Permissions::ATTACH_FILES;
let overwrite = PermissionOverwrite {
    allow: allow,
    deny: deny,
    kind: PermissionOverwriteType::Member(user_id),
};

let cache = CACHE.read().unwrap();
let channel = cache
    .guild_channel(channel_id)
    .ok_or(ModelError::ItemMissing)?;

channel.read().unwrap().create_permission(&overwrite)?;

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

Deletes this channel, returning the channel on a successful deletion.

fn delete_messages(&self, message_ids: &[MessageId]) -> Result<()>

Deletes all messages by Ids from the given vector in the channel.

Refer to Channel::delete_messages for more information.

Requires the Manage Messages permission.

Note: This uses bulk delete endpoint which is not available for user accounts.

Note: Messages that are older than 2 weeks can't be deleted using this method.

fn delete_permission(
    &self,
    permission_type: PermissionOverwriteType
) -> Result<()>

Deletes all permission overrides in the channel from a member or role.

Note: Requires the Manage Channel permission.

fn delete_reaction<M, R>(
    &self,
    message_id: M,
    user_id: Option<UserId>,
    reaction_type: R
) -> Result<()> where
    M: Into<MessageId>,
    R: Into<ReactionType>, 

Deletes the given Reaction from the channel.

Note: Requires the Manage Messages permission, if the current user did not perform the reaction.

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

Modifies a channel's settings, such as its position or name.

Refer to EditChannels documentation for a full list of methods.

Examples

Change a voice channels name and bitrate:

channel.edit(|c| c.name("test").bitrate(86400));

fn edit_message<F, M>(&self, message_id: M, f: F) -> Result<Message> where
    F: FnOnce(CreateMessage) -> CreateMessage,
    M: Into<MessageId>, 

Edits a Message in the channel given its Id.

Message editing preserves all unchanged message data.

Refer to the documentation for CreateMessage for more information regarding message restrictions and requirements.

Note: Requires that the current user be the author of the message.

Errors

Returns a ModelError::MessageTooLong if the content of the message is over the the limit, containing the number of unicode code points over the limit.

fn guild(&self) -> Option<Arc<RwLock<Guild>>>

Attempts to find this channel's guild in the Cache.

Note: Right now this performs a clone of the guild. This will be optimized in the future.

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

Gets all of the channel's invites.

Requires the Manage Channels permission.

fn is_nsfw(&self) -> bool

Determines if the channel is NSFW.

Refer to utils::is_nsfw for more details.

Only text channels are taken into consideration as being NSFW. voice channels are never NSFW.

fn message<M: Into<MessageId>>(&self, message_id: M) -> Result<Message>

Gets a message from the channel.

Requires the Read Message History permission.

fn messages<F>(&self, f: F) -> Result<Vec<Message>> where
    F: FnOnce(GetMessages) -> GetMessages, 

Gets messages from the channel.

Refer to Channel::messages for more information.

Requires the Read Message History permission.

fn name(&self) -> &str

Returns the name of the guild channel.

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

Calculates the permissions of a member.

The Id of the argument must be a Member of the Guild that the channel is in.

Examples

Calculate the permissions of a User who posted a Message in a channel:

use serenity::prelude::*;
use serenity::model::*;
struct Handler;

use serenity::CACHE;

impl EventHandler for Handler {
    fn on_message(&self, _: Context, msg: Message) {
        let channel = match CACHE.read().unwrap().guild_channel(msg.channel_id) {
            Some(channel) => channel,
            None => return,
        };

        let permissions = channel.read().unwrap().permissions_for(&msg.author).unwrap();

        println!("The user's permissions: {:?}", permissions);
    }
}
let mut client = Client::new("token", Handler); client.start().unwrap();

Check if the current user has the Attach Files and Send Messages permissions (note: serenity will automatically check this for; this is for demonstrative purposes):

use serenity::prelude::*;
use serenity::model::*;
use serenity::CACHE;
use serenity::model::permissions;
use std::fs::File;

struct Handler;

impl EventHandler for Handler {
    fn on_message(&self, _: Context, msg: Message) {
        let channel = match CACHE.read().unwrap().guild_channel(msg.channel_id) {
            Some(channel) => channel,
            None => return,
        };

        let current_user_id = CACHE.read().unwrap().user.id;
let permissions =
channel.read().unwrap().permissions_for(current_user_id).unwrap();

if !permissions.contains(Permissions::ATTACH_FILES |
Permissions::SEND_MESSAGES) {
            return;
        }

        let file = match File::open("./cat.png") {
            Ok(file) => file,
            Err(why) => {
                println!("Err opening file: {:?}", why);

                return;
            },
        };

let _ = msg.channel_id.send_files(vec![(&file, "cat.png")], |m|
m.content("here's a cat"));
    }
}

let mut client = Client::new("token", Handler); client.start().unwrap();

Errors

Returns a ModelError::GuildNotFound if the channel's guild could not be found in the Cache.

fn pin<M: Into<MessageId>>(&self, message_id: M) -> Result<()>

Pins a [Message] to the channel.

fn pins(&self) -> Result<Vec<Message>>

Gets all channel's pins.

fn reaction_users<M, R, U>(
    &self,
    message_id: M,
    reaction_type: R,
    limit: Option<u8>,
    after: Option<U>
) -> Result<Vec<User>> where
    M: Into<MessageId>,
    R: Into<ReactionType>,
    U: Into<UserId>, 

Gets the list of Users who have reacted to a Message with a certain Emoji.

Refer to Channel::reaction_users for more information.

Note: Requires the Read Message History permission.

fn say(&self, content: &str) -> Result<Message>

Sends a message with just the given message content in the channel.

Errors

Returns a ModelError::MessageTooLong if the content of the message is over the above limit, containing the number of unicode code points over the limit.

fn send_files<'a, F, T>(&self, files: Vec<T>, f: F) -> Result<Message> where
    F: FnOnce(CreateMessage) -> CreateMessage,
    T: Into<AttachmentType<'a>>, 

Sends (a) file(s) along with optional message contents.

Refer to ChannelId::send_files for examples and more information.

The Attach Files and Send Messages permissions are required.

Note: Message contents must be under 2000 unicode code points.

Errors

If the content of the message is over the above limit, then a ClientError::MessageTooLong will be returned, containing the number of unicode code points over the limit.

fn send_message<F: FnOnce(CreateMessage) -> CreateMessage>(
    &self,
    f: F
) -> Result<Message>

Sends a message to the channel with the given content.

Note: This will only work when a Message is received.

Note: Requires the Send Messages permission.

Errors

Returns a ModelError::MessageTooLong if the content of the message is over the above limit, containing the number of unicode code points over the limit.

Returns a ModelError::InvalidPermissions if the current user does not have the required permissions.

fn unpin<M: Into<MessageId>>(&self, message_id: M) -> Result<()>

Unpins a Message in the channel given by its Id.

Requires the Manage Messages permission.

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

Retrieves the channel's webhooks.

Note: Requires the Manage Webhooks permission.

Trait Implementations

impl Clone for GuildChannel

fn clone(&self) -> GuildChannel

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for GuildChannel

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

Formats the value using the given formatter.

impl Display for GuildChannel

fn fmt(&self, f: &mut Formatter) -> FmtResult

Formats the channel, creating a mention of it.