[−][src]Struct serenity::client::Client
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
Shard
s. 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::prelude::*; use serenity::Client; struct Handler; #[serenity::async_trait] impl EventHandler for Handler { async fn message(&self, context: Context, msg: Message) { if msg.content == "!ping" { let _ = msg.channel_id.say(&context, "Pong!"); } } } let mut client = Client::builder("my token here").event_handler(Handler).await?; client.start().await?;
Fields
data: Arc<RwLock<TypeMap>>
A TypeMap 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:
use serenity::prelude::*; use serenity::model::prelude::*; use std::collections::HashMap; use std::env; struct MessageEventCounter; impl TypeMapKey for MessageEventCounter { type Value = HashMap<String, u64>; } async fn reg<S: Into<String>>(ctx: Context, name: S) { let mut data = ctx.data.write().await; let counter = data.get_mut::<MessageEventCounter>().unwrap(); let entry = counter.entry(name.into()).or_insert(0); *entry += 1; } struct Handler; #[serenity::async_trait] impl EventHandler for Handler { async fn message(&self, ctx: Context, _: Message) { reg(ctx, "MessageCreate").await } async fn message_delete(&self, ctx: Context, _: ChannelId, _: MessageId) { reg(ctx, "MessageDelete").await } async fn message_delete_bulk(&self, ctx: Context, _: ChannelId, _: Vec<MessageId>) { reg(ctx, "MessageDeleteBulk").await } #[cfg(feature = "cache")] async fn message_update(&self, ctx: Context, _old: Option<Message>, _new: Option<Message>, _: MessageUpdateEvent) { reg(ctx, "MessageUpdate").await } #[cfg(not(feature = "cache"))] async fn message_update(&self, ctx: Context, _new_data: MessageUpdateEvent) { reg(ctx, "MessageUpdate").await } } let token = std::env::var("DISCORD_TOKEN")?; let mut client = Client::builder(&token).event_handler(Handler).await?; { let mut data = client.data.write().await; data.insert::<MessageEventCounter>(HashMap::default()); } client.start().await?;
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 token = std::env::var("DISCORD_TOKEN")?; let mut client = Client::builder(&token).event_handler(Handler).await?; let shard_manager = client.shard_manager.clone(); tokio::spawn(async move { loop { let sm = shard_manager.lock().await; let count = sm.shards_instantiated().await.len(); println!("Shard count instantiated: {}", count); tokio::time::delay_for(Duration::from_millis(5000)).await; } });
Shutting down all connections after one minute of operation:
use serenity::client::{Client, EventHandler}; use std::time::Duration; struct Handler; impl EventHandler for Handler { } let token = std::env::var("DISCORD_TOKEN")?; let mut client = Client::builder(&token).event_handler(Handler).await?; // 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. tokio::spawn(async move { tokio::time::delay_for(Duration::from_secs(60)); shard_manager.lock().await.shutdown_all().await; println!("Shutdown shard manager!"); }); println!("Client shutdown: {:?}", client.start().await);
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.
cache_and_http: Arc<CacheAndHttp>
A container for an optional cache and HTTP client. It also contains the cache update timeout.
Implementations
impl Client
[src]
pub fn new<'a>(token: impl AsRef<str>) -> ClientBuilder<'a>ⓘNotable traits for ClientBuilder<'a>
impl<'a> Future for ClientBuilder<'a> type Output = Result<Client>;
[src]
Notable traits for ClientBuilder<'a>
impl<'a> Future for ClientBuilder<'a> type Output = Result<Client>;
please use builder
instead
Returns a builder implementing Future
. You can chain the builder methods and then await
in order to finish the Client
.
pub fn builder<'a>(token: impl AsRef<str>) -> ClientBuilder<'a>ⓘNotable traits for ClientBuilder<'a>
impl<'a> Future for ClientBuilder<'a> type Output = Result<Client>;
[src]
Notable traits for ClientBuilder<'a>
impl<'a> Future for ClientBuilder<'a> type Output = Result<Client>;
pub async 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:
use serenity::Client; struct Handler; impl EventHandler for Handler {} let token = std::env::var("DISCORD_TOKEN")?; let mut client = Client::builder(&token).event_handler(Handler).await?; if let Err(why) = client.start().await { println!("Err with client: {:?}", why); }
pub async 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:
use serenity::Client; struct Handler; impl EventHandler for Handler {} let token = std::env::var("DISCORD_TOKEN")?; let mut client = Client::builder(&token).event_handler(Handler).await?; if let Err(why) = client.start_autosharded().await { println!("Err with client: {:?}", why); }
Errors
Returns a ClientError::Shutdown
when all shards have shutdown due to
an error.
pub async fn start_shard<'_>(
&'_ mut self,
shard: u64,
shards: u64
) -> Result<()>
[src]
&'_ mut self,
shard: u64,
shards: u64
) -> Result<()>
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:
use serenity::Client; struct Handler; impl EventHandler for Handler {} let token = std::env::var("DISCORD_TOKEN")?; let mut client = Client::builder(&token).event_handler(Handler).await?; if let Err(why) = client.start_shard(3, 5).await { println!("Err with client: {:?}", why); }
Start shard 0 of 1 (you may also be interested in start
or
start_autosharded
):
use serenity::Client; struct Handler; impl EventHandler for Handler {} let token = std::env::var("DISCORD_TOKEN")?; let mut client = Client::builder(&token).event_handler(Handler).await?; if let Err(why) = client.start_shard(0, 1).await { println!("Err with client: {:?}", why); }
Errors
Returns a ClientError::Shutdown
when all shards have shutdown due to
an error.
pub async 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:
use serenity::Client; struct Handler; impl EventHandler for Handler {} let token = std::env::var("DISCORD_TOKEN")?; let mut client = Client::builder(&token).event_handler(Handler).await?; if let Err(why) = client.start_shards(8).await { println!("Err with client: {:?}", why); }
Errors
Returns a ClientError::Shutdown
when all shards have shutdown due to
an error.
pub async fn start_shard_range<'_>(
&'_ mut self,
range: [u64; 2],
total_shards: u64
) -> Result<()>
[src]
&'_ mut self,
range: [u64; 2],
total_shards: u64
) -> Result<()>
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; struct Handler; impl EventHandler for Handler {} let token = std::env::var("DISCORD_TOKEN")?; let mut client = Client::builder(&token).event_handler(Handler).await?; if let Err(why) = client.start_shard_range([4, 7], 10).await { println!("Err with client: {:?}", why); }
Errors
Returns a ClientError::Shutdown
when all shards have shutdown due to
an error.
Auto Trait Implementations
impl !RefUnwindSafe for Client
impl Send for Client
impl Sync for Client
impl Unpin for Client
impl !UnwindSafe for Client
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T> Instrument for T
[src]
fn instrument(self, span: Span) -> Instrumented<Self>
[src]
fn in_current_span(self) -> Instrumented<Self>
[src]
impl<T> Instrument for T
[src]
fn instrument(self, span: Span) -> Instrumented<Self>
[src]
fn in_current_span(self) -> Instrumented<Self>
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> Same<T> for T
type Output = T
Should always be Self
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
V: MultiLane<T>,
pub fn vzip(self) -> V
impl<T> WithSubscriber for T
[src]
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
[src]
S: Into<Dispatch>,