Struct serenity::client::gateway::Shard

pub struct Shard { /* 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.

Methods

impl Shard

fn new(base_url: &str,
       token: &str,
       shard_info: Option<[u64; 2]>,
       login_type: LoginType)
       -> Result<(Shard, ReadyEvent, Receiver<WebSocketStream>)>

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::client::gateway::Shard;
use serenity::client::{LoginType, rest};
use std::env;

let token = env::var("DISCORD_BOT_TOKEN").expect("Token in environment");
// retrieve the gateway response, which contains the URL to connect to
let gateway = rest::get_gateway().expect("Valid gateway response").url;
let shard = Shard::new(&gateway, &token, None, LoginType::Bot)
    .expect("Working shard");

// at this point, you can create a `loop`, and receive events and match
// their variants

fn shard_info(&self) -> Option<[u64; 2]>

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".

fn set_afk(&mut self, afk: bool)

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>)

Sets the user's current game, if any.

Other presence settings are maintained.

fn set_status(&mut self, online_status: OnlineStatus)

Sets the user's current online status.

Note that Offline is not a valid presence, so it is automatically converted to Invisible.

Other presence settings are maintained.

fn set_presence(&mut self, game: Option<Game>, status: OnlineStatus, afk: bool)

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};

// assuming you are in a context

context.shard.lock()
    .unwrap()
    .set_presence(Some(Game::playing("Heroes of the Storm")),
                  OnlineStatus::Online,
                  false);

fn latency(&self) -> Option<StdDuration>

Calculates the heartbeat latency (in nanoseconds) between the shard and Discord.

fn shutdown(receiver: &mut Receiver<WebSocketStream>) -> Result<()>

fn sync_calls(&self, channels: &[ChannelId])

Syncs a number of [Call]s, given by their associated channel Ids. This will allow the current user to know what calls are currently occurring, as otherwise events will not be received.

fn chunk_guilds(&self,
                guild_ids: &[GuildId],
                limit: Option<u16>,
                query: Option<&str>)

Requests that one or multiple [Guild]s be synced.

This will ask Discord 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.

fn sync_guilds(&self, guild_ids: &[GuildId])

Syncs the user's guilds.