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

Methods

impl Shard
[src]

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

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

Sets whether the current user is afk. This helps Discord determine where to send notifications.

Other presence settings are maintained.

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

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

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

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.

client.on_message(|ctx, msg| {
    if msg.content == "~ping" {
        if let Some(latency) = ctx.shard.lock().unwrap().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");
        }
    }
});

Shuts down the receiver by attempting to cleanly close the connection.

Uncleanly shuts down the receiver by not sending a close code.

Requests that one or multiple Guilds 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 Members, 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"));

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