Struct serenity::gateway::Shard
[−]
[src]
pub struct Shard { pub client: Client<TlsStream<TcpStream>>, // some fields omitted }
A Shard is a higher-level handler for a websocket connection to Discord's gateway. The shard allows for sending and receiving messages over the websocket, such as setting the active game, reconnecting, syncing guilds, and more.
Refer to the module-level documentation for information on effectively using multiple shards, if you need to.
Note that there are additional methods available if you are manually managing a shard yourself, although they are hidden from the documentation since there are few use cases for doing such.
Stand-alone shards
You may instantiate a shard yourself - decoupled from the Client
- if
you need to. For most use cases, you will not need to do this, and you can
leave the client to do it.
This can be done by passing in the required parameters to new
. You can
then manually handle the shard yourself and receive events via
receive
.
Note: You really do not need to do this. Just call one of the
appropriate methods on the Client
.
Examples
See the documentation for new
on how to use this.
Fields
client: Client<TlsStream<TcpStream>>
Methods
impl Shard
[src]
fn new(
ws_url: Arc<Mutex<String>>,
token: Arc<Mutex<String>>,
shard_info: [u64; 2]
) -> Result<Shard>
[src]
ws_url: Arc<Mutex<String>>,
token: Arc<Mutex<String>>,
shard_info: [u64; 2]
) -> Result<Shard>
Instantiates a new instance of a Shard, bypassing the client.
Note: You should likely never need to do this yourself.
Examples
Instantiating a new Shard manually for a bot with no shards, and then listening for events:
use serenity::gateway::Shard; use serenity::http; use std::env; let token = env::var("DISCORD_TOKEN").expect("Token in environment"); // retrieve the gateway response, which contains the URL to connect to let gateway = http::get_gateway().expect("Valid gateway response").url; let shard = Shard::new(&gateway, &token, None) .expect("Working shard"); // at this point, you can create a `loop`, and receive events and match // their variants
fn is_shutdown(&self) -> bool
[src]
Whether the shard has permanently shutdown.
This should normally happen due to manual calling of shutdown
or
shutdown_clean
.
[src]
Retrieves a copy of the current shard information.
The first element is the current shard - 0-indexed - while the second element is the total number of shards -- 1-indexed.
For example, if using 3 shards in total, and if this is shard 1, then it can be read as "the second of three shards".
Examples
Retrieving the shard info for the second shard, out of two shards total:
assert_eq!(shard.shard_info(), [1, 2]);
fn set_afk(&mut self, afk: bool)
[src]
Sets whether the current user is afk. This helps Discord determine where to send notifications.
Other presence settings are maintained.
fn set_game(&mut self, game: Option<Game>)
[src]
Sets the user's current game, if any.
Other presence settings are maintained.
Examples
Setting the current game to playing "Heroes of the Storm"
:
use serenity::model::Game; shard.set_game(Some(Game::playing("Heroes of the Storm")));
fn set_status(&mut self, online_status: OnlineStatus)
[src]
Sets the user's current online status.
Note that Offline
is not a valid online status, so it is
automatically converted to Invisible
.
Other presence settings are maintained.
Examples
Setting the current online status for the shard to DoNotDisturb
.
use serenity::model::OnlineStatus; shard.set_status(OnlineStatus::DoNotDisturb);
fn set_presence(&mut self, game: Option<Game>, status: OnlineStatus, afk: bool)
[src]
Sets the user's full presence information.
Consider using the individual setters if you only need to modify one of these.
Examples
Set the current user as playing "Heroes of the Storm"
, being online,
and not being afk:
use serenity::model::{Game, OnlineStatus}; shard.set_presence(Some(Game::playing("Heroes of the Storm")), OnlineStatus::Online, false);
fn stage(&self) -> ConnectionStage
[src]
Returns the current connection stage of the shard.
fn latency(&self) -> Option<StdDuration>
[src]
Calculates the heartbeat latency between the shard and the gateway.
Examples
When using the Client
, output the latency in response to a "~ping"
message handled through [Client::on_message
].
struct Handler; impl EventHandler for Handler { fn on_message(&self, ctx: Context, msg: Message) { if msg.content == "~ping" { if let Some(latency) = ctx.shard.lock().latency() { let s = format!("{}.{}s", latency.as_secs(), latency.subsec_nanos()); let _ = msg.channel_id.say(&s); } else { let _ = msg.channel_id.say("N/A"); } } } } let mut client = Client::new("token", Handler); client.start().unwrap();
fn shutdown_clean(&mut self) -> Result<()>
[src]
Shuts down the receiver by attempting to cleanly close the connection.
fn shutdown(&mut self) -> Result<()>
[src]
Uncleanly shuts down the receiver by not sending a close code.
fn chunk_guilds<T: AsRef<GuildId>, It>(
&mut self,
guild_ids: It,
limit: Option<u16>,
query: Option<&str>
) where
It: IntoIterator<Item = T>,
[src]
&mut self,
guild_ids: It,
limit: Option<u16>,
query: Option<&str>
) where
It: IntoIterator<Item = T>,
Requests that one or multiple Guild
s be chunked.
This will ask the gateway to start sending member chunks for large guilds (250 members+). If a guild is over 250 members, then a full member list will not be downloaded, and must instead be requested to be sent in "chunks" containing members.
Member chunks are sent as the Event::GuildMembersChunk
event. Each
chunk only contains a partial amount of the total members.
If the cache
feature is enabled, the cache will automatically be
updated with member chunks.
Examples
Chunk a single guild by Id, limiting to 2000 Member
s, and not
specifying a query parameter:
use serenity::model::GuildId; let guild_ids = vec![GuildId(81384788765712384)]; shard.chunk_guilds(&guild_ids, Some(2000), None);
Chunk a single guild by Id, limiting to 20 members, and specifying a
query parameter of "do"
:
use serenity::model::GuildId; let guild_ids = vec![GuildId(81384788765712384)]; shard.chunk_guilds(&guild_ids, Some(20), Some("do"));
fn guilds_handled(&self) -> u16
[src]
Calculates the number of guilds that the shard is responsible for.
If sharding is not being used (i.e. 1 shard), then the total number of
Guild
in the Cache
will be used.
Note: Requires the cache
feature be enabled.
Examples
Retrieve the number of guilds a shard is responsible for:
let info = shard.shard_info(); let guilds = shard.guilds_handled(); println!("Shard {:?} is responsible for {} guilds", info, guilds);