Struct serenity::client::Client [−] [src]

pub struct Client {
    pub data: Arc<Mutex<ShareMap>>,
    // some fields omitted
}

The Client is the way to "login" and be able to start sending authenticated requests over the REST API, as well as initializing a WebSocket connection through Shards. Refer to the documentation on using sharding for more information.

Event Handlers

Event handlers can be configured. For example, the event handler on_message will be dispatched to whenever a Event::MessageCreate is received over the connection.

Note that you do not need to manually handle events, as they are handled internally and then dispatched to your event handlers.

Examples

Creating a Client instance and adding a handler on every message receive, acting as a "ping-pong" bot is simple:

use serenity::Client;

let mut client = Client::login_bot("my token here");

client.on_message(|context, message| {
    if message.content == "!ping" {
        context.say("Pong!");
    }
});

client.start();

Fields

A ShareMap which requires types to be Send + Sync. This is a map that can be safely shared across contexts.

The purpose of the data field is to be accessible and persistent across contexts; that is, data can be modified by one context, and will persist through the future and be accessible through other contexts. This is useful for anything that should "live" through the program: counters, database connections, custom user caches, etc.

In the meaning of a context, this data can be accessed through Context::data.

Refer to example 06 for an example on using the data field.

Methods

impl Client
[src]

Creates a Client for a bot user.

Discord has a requirement of prefixing bot tokens with "Bot ", which this function will automatically do for you if not already included.

Creates a Client for a user.

Note: Read the notes for LoginType::User prior to using this, as there are restrictions on usage.

Sets a framework to be used with the client. All message events will be passed through the framework after being passed to the on_message event handler.

See the framework module-level documentation for more information on usage.

Establish the connection and start listening for events.

This will start receiving events in a loop and start dispatching the events to your registered handlers.

Note that this should be used only for users and for bots which are in less than 2500 guilds. If you have a reason for sharding and/or are in more than 2500 guilds, use one of these depending on your use case:

Refer to the Gateway documentation for more information on effectively using sharding.

Establish the connection(s) and start listening for events.

This will start receiving events in a loop and start dispatching the events to your registered handlers.

This will retrieve an automatically determined number of shards to use from the API - determined by Discord - and then open a number of shards equivalent to that amount.

Refer to the Gateway documentation for more information on effectively using sharding.

Establish a sharded connection and start listening for events.

This will start receiving events and dispatch them to your registered handlers.

This will create a single shard by ID. If using one shard per process, you will need to start other processes with the other shard IDs in some way.

Refer to the Gateway documentation for more information on effectively using sharding.

Establish sharded connections and start listening for events.

This will start receiving events and dispatch them to your registered handlers.

This will create and handle all shards within this single process. If you only need to start a single shard within the process, or a range of shards, use start_shard or start_shard_range, respectively.

Refer to the Gateway documentation for more information on effectively using sharding.

Establish a range of sharded connections and start listening for events.

This will start receiving events and dispatch them to your registered handlers.

This will create and handle all shards within a given range within this single process. If you only need to start a single shard within the process, or all shards within the process, use start_shard or start_shards, respectively.

Refer to the Gateway documentation for more information on effectively using sharding.

Examples

For a bot using a total of 10 shards, initialize shards 4 through 7:

use serenity::Client;
use std::env;

let token = env::var("DISCORD_BOT_TOKEN").unwrap();
let mut client = Client::login_bot(&token);

let _ = client.start_shard_range([4, 7], 10);

Attaches a handler for when a CallCreate is received.

Attaches a handler for when a ChannelCreate is received.

Attaches a handler for when a ChannelDelete is received.

Attaches a handler for when a ChannelPinsAck is received.

Attaches a handler for when a ChannelPinsUpdate is received.

Attaches a handler for when a FriendSuggestionCreate is received.

Attaches a handler for when a FriendSuggestionDelete is received.

Attaches a handler for when a GuildCreate is received.

Attaches a handler for when a GuildEmojisUpdate is received.

The HashMap of emojis is the new full list of emojis.

Attaches a handler for when a GuildIntegrationsUpdate is received.

Attaches a handler for when a GuildMemberAdd is received.

Attaches a handler for when a GuildMembersChunk is received.

Attaches a handler for when a GuildRoleCreate is received.

Attaches a handler for when a GuildRoleSync is received.

Attaches a handler for when a GuildUnavailable is received.

Attaches a handler for when a GuildBan is received.

Attaches a handler for when a GuildUnban is received.

Attaches a handler for when a MessageCreate is received.

Examples

Print the contents of every received message:

use serenity::Client;

let mut client = Client::login_bot("bot token here");

client.on_message(|_context, message| {
    println!("{}", message.content);
});

let _ = client.start();

Attaches a handler for when a MessageAck is received.

Attaches a handler for when a MessageDelete is received.

Attaches a handler for when a MessageDeleteBulk is received.

Attaches a handler for when a MessageUpdate is received.

Attaches a handler for when a PresencesReplace is received.

Attaches a handler for when a PresenceUpdate is received.

Attached a handler for when a ReactionAdd is received.

Attached a handler for when a ReactionRemove is received.

Attached a handler for when a ReactionRemoveAll is received.

Register an event to be called whenever a Ready event is received.

Registering a handler for the ready event is good for noting when your bot has established a connection to the gateway through a Shard.

Note: The Ready event is not guarenteed to be the first event you will receive by Discord. Do not actively rely on it.

Examples

Print the current user's name on ready:

use serenity::Client;
use std::env;

let token = env::var("DISCORD_BOT_TOKEN").unwrap();
let mut client = Client::login_bot(&token);

client.on_ready(|_context, ready| {
    println!("{} is connected", ready.user.name);
});

Attaches a handler for when a ChannelRecipientAdd is received.

Attaches a handler for when a ChannelRecipientRemove is received.

Attaches a handler for when a RelationshipAdd is received.

Attaches a handler for when a RelationshipRemove is received.

Attaches a handler for when a Resumed is received.

Attaches a handler for when a TypingStart is received.

Attaches a handler for when an Unknown is received.

Attaches a handler for when a VoiceServerUpdate is received.

Attaches a handler for when a VoiceStateUpdate is received.

Attaches a handler for when a WebhookUpdate is received.

impl Client
[src]

Attaches a handler for when a CallDelete is received.

The ChannelId is the Id of the channel hosting the call. Returns the call from the cache - optionally - if the call was in it.

Attaches a handler for when a CallUpdate is received.

Attaches a handler for when a ChannelUpdate is received.

Optionally provides the version of the channel before the update.

Attaches a handler for when a GuildDelete is received.

Returns a partial guild as well as - optionally - the full guild, with data like Roles. This can be None in the event that it was not in the Cache.

Note: The relevant guild is removed from the Cache when this event is received. If you need to keep it, you can either re-insert it yourself back into the Cache or manage it in another way.

Attaches a handler for when a GuildMemberRemove is received.

Returns the user's associated Member object, if it existed in the cache.

Attaches a handler for when a GuildMemberUpdate is received.

Attaches a handler for when a GuildRoleDelete is received.

Attaches a handler for when a GuildRoleUpdate is received.

The optional Role is the role prior to updating. This can be None if it did not exist in the Cache before the update.

Attaches a handler for when a UserGuildSettingsUpdate is received.

Attaches a handler for when a GuildUpdate is received.

Attaches a handler for when a UserNoteUpdate is received.

Optionally returns the old note for the User, if one existed.

Attaches a handler for when a UserSettingsUpdate is received.

The old user settings will be provided as well.

Attaches a handler for when a UserUpdate is received.

The old current user will be provided as well.