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

pub struct Client {
    pub data: Arc<Mutex<ShareMap>>,
    pub shard_manager: Arc<Mutex<ShardManager>>,
    pub threadpool: ThreadPool,
    pub token: Arc<Mutex<String>>,
    pub voice_manager: Arc<Mutex<ClientVoiceManager>>,
    pub ws_uri: Arc<Mutex<String>>,
    // some fields omitted
}

The Client is the way to 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 EventHandler::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::prelude::*;
use serenity::model::*;

struct Handler;

impl EventHandler for Handler {
    fn on_message(&self, _: Context, msg: Message) {
        if msg.content == "!ping" {
            let _ = msg.channel_id.say("Pong!");
        }
    }
}

let mut client = Client::new("my token here", Handler);

client.start();

Fields

data: Arc<Mutex<ShareMap>>

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.

Examples

Create a MessageEventCounter to track the following events:

extern crate serenity;
extern crate typemap;

use serenity::prelude::*;
use serenity::model::*;
use std::collections::HashMap;
use std::env;
use typemap::Key;

struct MessageEventCounter;

impl Key for MessageEventCounter {
    type Value = HashMap<String, u64>;
}

macro_rules! reg {
    ($ctx:ident $name:expr) => {
        {
            let mut data = $ctx.data.lock();
            let counter = data.get_mut::<MessageEventCounter>().unwrap();
            let entry = counter.entry($name).or_insert(0);
            *entry += 1;
        }
    };
}

struct Handler;

impl EventHandler for Handler {
    fn on_message(&self, ctx: Context, _: Message) { reg!(ctx "MessageCreate") }
    fn on_message_delete(&self, ctx: Context, _: ChannelId, _: MessageId) {
        reg!(ctx "MessageDelete") }
    fn on_message_delete_bulk(&self, ctx: Context, _: ChannelId, _: Vec<MessageId>) {
        reg!(ctx "MessageDeleteBulk") }
    fn on_message_update(&self, ctx: Context, _: ChannelId, _: MessageId) {
        reg!(ctx "MessageUpdate") }
}

let mut client = Client::new(&env::var("DISCORD_TOKEN").unwrap(), Handler);

{
    let mut data = client.data.lock();
    data.insert::<MessageEventCounter>(HashMap::default());
}

client.start().unwrap();

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

shard_manager: Arc<Mutex<ShardManager>>

A HashMap of all shards instantiated by the Client.

The key is the shard ID and the value is the shard itself.

Examples

If you call client.start_shard(3, 5), this HashMap will only ever contain a single key of 3, as that's the only Shard the client is responsible for.

If you call client.start_shards(10), this HashMap will contain keys 0 through 9, one for each shard handled by the client.

Printing the number of shards currently instantiated by the client every 5 seconds:



struct Handler;

impl EventHandler for Handler { }

let mut client = Client::new(&env::var("DISCORD_TOKEN")?, Handler)?;

let shard_manager = client.shard_manager.clone();

thread::spawn(move || {
    loop {
        println!("Shard count instantiated: {}",
                 shard_manager.lock().shards_instantiated().len());

        thread::sleep(Duration::from_millis(5000));
    }
});

Shutting down all connections after one minute of operation:

use serenity::client::{Client, EventHandler};
use std::time::Duration;
use std::{env, thread};

struct Handler;

impl EventHandler for Handler { }

let mut client = Client::new(&env::var("DISCORD_TOKEN")?, Handler)?;

// Create a clone of the `Arc` containing the shard manager.
let shard_manager = client.shard_manager.clone();

// Create a thread which will sleep for 60 seconds and then have the
// shard manager shutdown.
thread::spawn(move || {
    thread::sleep(Duration::from_secs(60));

    shard_manager.lock().shutdown_all();

    println!("Shutdown shard manager!");
});

println!("Client shutdown: {:?}", client.start());

threadpool: ThreadPool

The threadpool shared by all shards.

Defaults to 5 threads, which should suffice small bots. Consider increasing this number as your bot grows.

token: Arc<Mutex<String>>

The token in use by the client.

voice_manager: Arc<Mutex<ClientVoiceManager>>

The voice manager for the client.

This is an ergonomic structure for interfacing over shards' voice connections.

ws_uri: Arc<Mutex<String>>

URI that the client's shards will use to connect to the gateway.

This is likely not important for production usage and is, at best, used for debugging.

This is wrapped in an Arc<Mutex<T>> so all shards will have an updated value available.

Methods

`impl Client`
[src]

`pub fn new<H>(token: &str, handler: H) -> Result<Self> where H: EventHandler + Send + Sync + 'static,`
[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.

Examples

Create a Client, using a token from an environment variable:

struct Handler;

impl EventHandler for Handler {}
use serenity::Client;
use std::env;

let token = env::var("DISCORD_TOKEN")?;
let client = Client::new(&token, Handler)?;

`pub fn with_framework<F: Framework + Send + 'static>(&mut self, f: F)`
[src]

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

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

Examples

Create a simple framework that responds to a ~ping command:

use serenity::framework::StandardFramework;

struct Handler;

impl EventHandler for Handler {}
use serenity::Client;
use std::env;

let mut client = Client::new(&env::var("DISCORD_TOKEN")?, Handler)?;
client.with_framework(StandardFramework::new()
    .configure(|c| c.prefix("~"))
    .on("ping", |_, msg, _| {
        msg.channel_id.say("Pong!")?;

        Ok(())
     }));

Using your own framework:

use serenity::Framework;
use serenity::client::Context;
use serenity::model::*;
use tokio_core::reactor::Handle;
use std::collections::HashMap;


struct MyFramework {
    commands: HashMap<String, Box<Fn(Message, Vec<String>)>>,
}

impl Framework for MyFramework {
    fn dispatch(&mut self, _: Context, msg: Message, tokio_handle: &Handle) {
        let args = msg.content.split_whitespace();
        let command = match args.next() {
            Some(command) => {
                if !command.starts_with('*') { return; }
                command
            },
            None => return,
        };

        let command = match self.commands.get(&command) {
            Some(command) => command, None => return,
        };

        tokio_handle.spawn_fn(move || { (command)(msg, args); Ok() });
    }
}

struct Handler;

impl EventHandler for Handler {}

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

let mut client = Client::new(&token, Handler).unwrap();
client.with_framework(MyFramework { commands: {
    let mut map = HashMap::new();
    map.insert("ping".to_string(), Box::new(|msg, _| msg.channel_id.say("pong!")));
    map
}});

Refer to the documentation for the framework module for more in-depth information.

`pub fn start(&mut self) -> Result<()>`
[src]

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.

Examples

Starting a Client with only 1 shard, out of 1 total:

struct Handler;

impl EventHandler for Handler {}
use serenity::client::Client;
use std::env;

let token = env::var("DISCORD_TOKEN")?;
let mut client = Client::new(&token, Handler).unwrap();

if let Err(why) = client.start() {
    println!("Err with client: {:?}", why);
}

`pub fn start_autosharded(&mut self) -> Result<()>`
[src]

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.

Examples

Start as many shards as needed using autosharding:

struct Handler;

impl EventHandler for Handler {}
use serenity::client::Client;
use std::env;

let token = env::var("DISCORD_TOKEN")?;
let mut client = Client::new(&token, Handler).unwrap();

if let Err(why) = client.start_autosharded() {
    println!("Err with client: {:?}", why);
}

Errors

Returns a ClientError::Shutdown when all shards have shutdown due to an error.

`pub fn start_shard(&mut self, shard: u64, shards: u64) -> Result<()>`
[src]

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.

Examples

Start shard 3 of 5:

struct Handler;

impl EventHandler for Handler {}
use serenity::client::Client;
use std::env;

let token = env::var("DISCORD_TOKEN")?;
let mut client = Client::new(&token, Handler).unwrap();

if let Err(why) = client.start_shard(3, 5) {
    println!("Err with client: {:?}", why);
}

Start shard 0 of 1 (you may also be interested in start or start_autosharded):

struct Handler;

impl EventHandler for Handler {}
use serenity::client::Client;
use std::env;

let mut client = Client::new(&env::var("DISCORD_TOKEN")?, Handler)?;

if let Err(why) = client.start_shard(0, 1) {
    println!("Err with client: {:?}", why);
}

Errors

Returns a ClientError::Shutdown when all shards have shutdown due to an error.

`pub fn start_shards(&mut self, total_shards: u64) -> Result<()>`
[src]

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.

Examples

Start all of 8 shards:

struct Handler;

impl EventHandler for Handler {}
use serenity::client::Client;
use std::env;

let token = env::var("DISCORD_TOKEN")?;
let mut client = Client::new(&token, Handler).unwrap();

if let Err(why) = client.start_shards(8) {
    println!("Err with client: {:?}", why);
}

Errors

Returns a ClientError::Shutdown when all shards have shutdown due to an error.

`pub fn start_shard_range( &mut self, range: [u64; 2], total_shards: u64 ) -> Result<()>`
[src]

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:

struct Handler;

impl EventHandler for Handler {}
use serenity::Client;
use std::env;

let token = env::var("DISCORD_TOKEN").unwrap();
let mut client = Client::new(&token, Handler);

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

struct Handler;

impl EventHandler for Handler {}
use serenity::client::Client;
use std::env;

let token = env::var("DISCORD_TOKEN")?;
let mut client = Client::new(&token, Handler).unwrap();

if let Err(why) = client.start_shard_range([4, 7], 10) {
    println!("Err with client: {:?}", why);
}

Errors

Returns a ClientError::Shutdown when all shards have shutdown due to an error.

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

Event Handlers

Examples

Fields

Examples

Examples

Methods

`impl Client`
[src]

`pub fn new<H>(token: &str, handler: H) -> Result<Self> where H: EventHandler + Send + Sync + 'static,`
[src]

Examples

`pub fn with_framework<F: Framework + Send + 'static>(&mut self, f: F)`
[src]

Examples

`pub fn start(&mut self) -> Result<()>`
[src]

Examples

`pub fn start_autosharded(&mut self) -> Result<()>`
[src]

Examples

Errors

`pub fn start_shard(&mut self, shard: u64, shards: u64) -> Result<()>`
[src]

Examples

Errors

`pub fn start_shards(&mut self, total_shards: u64) -> Result<()>`
[src]

Examples

Errors

`pub fn start_shard_range( &mut self, range: [u64; 2], total_shards: u64 ) -> Result<()>`
[src]

Examples

Errors

Auto Trait Implementations

`impl Send for Client`

`impl !Sync for Client`

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

Fields

Methods

impl Client[src]

pub fn new<H>(token: &str, handler: H) -> Result<Self> where H: EventHandler + Send + Sync + 'static, [src]

pub fn with_framework<F: Framework + Send + 'static>(&mut self, f: F)[src]

pub fn start(&mut self) -> Result<()>[src]

pub fn start_autosharded(&mut self) -> Result<()>[src]

pub fn start_shard(&mut self, shard: u64, shards: u64) -> Result<()>[src]

pub fn start_shards(&mut self, total_shards: u64) -> Result<()>[src]

pub fn start_shard_range( &mut self, range: [u64; 2], total_shards: u64) -> Result<()>[src]

Auto Trait Implementations

impl Send for Client

impl !Sync for Client

`impl Client`
[src]

`pub fn new<H>(token: &str, handler: H) -> Result<Self> where H: EventHandler + Send + Sync + 'static,`
[src]

`pub fn with_framework<F: Framework + Send + 'static>(&mut self, f: F)`
[src]

`pub fn start(&mut self) -> Result<()>`
[src]

`pub fn start_autosharded(&mut self) -> Result<()>`
[src]

`pub fn start_shard(&mut self, shard: u64, shards: u64) -> Result<()>`
[src]

`pub fn start_shards(&mut self, total_shards: u64) -> Result<()>`
[src]

`pub fn start_shard_range( &mut self, range: [u64; 2], total_shards: u64 ) -> Result<()>`
[src]

`impl Send for Client`

`impl !Sync for Client`