Struct songbird::Songbird

pub struct Songbird { /* private fields */ }

Available on crate feature gateway only.

A shard-aware struct responsible for managing Calls.

This manager transparently maps guild state and a source of shard information into individual calls, and forwards state updates which affect call state.

Implementations

impl Songbird

pub fn serenity() -> Arc<Self>

Available on crate feature serenity only.

Create a new Songbird instance for serenity.

This must be registered after creation.

pub fn serenity_from_config(config: Config) -> Arc<Self>

Available on crate feature serenity only.

Create a new Songbird instance for serenity, using the given configuration.

This must be registered after creation.

pub fn twilight<U>(cluster: Arc<TwilightMap>, user_id: U) -> Self

where U: Into<UserId>,

Available on crate feature twilight only.

Create a new Songbird instance for twilight.

Twilight handlers do not need to be registered, but users are responsible for passing in any events using process.

pub fn twilight_from_config<U>( sender_map: Arc<TwilightMap>, user_id: U, config: Config, ) -> Self

where U: Into<UserId>,

Available on crate feature twilight only.

Create a new Songbird instance for twilight.

Twilight handlers do not need to be registered, but users are responsible for passing in any events using process.

pub fn initialise_client_data<U: Into<UserId>>( &self, shard_count: u64, user_id: U, )

Set the bot’s user, and the number of shards in use.

If this struct is already initialised (e.g., from ::twilight), or a previous call, then this function is a no-op.

pub fn get<G: Into<GuildId>>(&self, guild_id: G) -> Option<Arc<Mutex<Call>>>

Retrieves a Call for the given guild, if one already exists.

pub fn get_or_insert<G>(&self, guild_id: G) -> Arc<Mutex<Call>>

where G: Into<GuildId>,

Retrieves a Call for the given guild, creating a new one if none is found.

This will not join any calls, or cause connection state to change.

pub fn iter(&self) -> Iter<'_>

Creates an iterator for all Calls currently managed.

pub fn set_config(&self, new_config: Config)

Sets a shared configuration for all drivers created from this manager.

Changes made here will apply to new Call and Driver instances only.

Requires the "driver" feature.

pub async fn join<C, G>( &self, guild_id: G, channel_id: C, ) -> JoinResult<Arc<Mutex<Call>>>

where C: Into<ChannelId>, G: Into<GuildId>,

Available on crate feature driver only.

Connects to a target by retrieving its relevant Call and connecting, or creating the handler if required.

This can also switch to the given channel, if a handler already exists for the target and the current connected channel is not equal to the given channel.

The provided channel ID is used as a connection target. The channel must be in the provided guild. This is not checked by the library, and will result in an error. If there is already a connected handler for the guild, and the provided channel is different from the channel that the connection is already connected to, then the handler will switch the connection to the provided channel.

If you only need to retrieve the handler for a target, then use get.

Twilight users should read the caveats mentioned in process.

NOTE: an Err(..) value will still create a Call accessible via get.

pub async fn join_gateway<C, G>( &self, guild_id: G, channel_id: C, ) -> JoinResult<(ConnectionInfo, Arc<Mutex<Call>>)>

where C: Into<ChannelId>, G: Into<GuildId>,

Partially connects to a target by retrieving its relevant Call and connecting, or creating the handler if required.

This method returns the handle and the connection info needed for other libraries or drivers, such as lavalink, and does not actually start or run a voice call.

NOTE: an Err(..) value will still create a Call accessible via get.

pub async fn leave<G: Into<GuildId>>(&self, guild_id: G) -> JoinResult<()>

Retrieves the handler for the given target and leaves the associated voice channel, if connected.

This will not drop the handler, and will preserve it and its settings. If you do not need to reuse event handlers, configuration, or active tracks in the underlying driver consider calling remove to release tasks, threads, and memory.

This is a wrapper around getting a handler and calling leave on it.

pub async fn remove<G: Into<GuildId>>(&self, guild_id: G) -> JoinResult<()>

Retrieves the Call for the given target and leaves the associated voice channel, if connected.

The handler is then dropped, removing settings for the target.

An Err(…) value implies that the gateway could not be contacted, and that leaving should be attempted again later (i.e., after reconnect).

impl Songbird

pub async fn process(&self, event: &TwilightEvent)

Available on crate feature twilight only.

Handle events received on the cluster.

When using twilight, you are required to call this with all inbound (voice) events, i.e., at least VoiceStateUpdates and VoiceServerUpdates.

Users must ensure that calls to this function happen on a separate task to any calls to join, join_gateway. The simplest way to ensure this is to tokio::spawn any command invocation.

Returned futures generally require the inner Call to be updated via this function, and will deadlock if event processing is not carried out on another spawned task.

Trait Implementations

impl Debug for Songbird

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> IntoIterator for &'a Songbird

type Item = <Iter<'a> as Iterator>::Item

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl VoiceGatewayManager for Songbird

Available on crate feature serenity only.

fn initialise<'life0, 'async_trait>( &'life0 self, shard_count: u32, user_id: SerenityUser, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Performs initial setup at the start of a connection to Discord.

fn register_shard<'life0, 'async_trait>( &'life0 self, shard_id: u32, sender: Sender<ShardRunnerMessage>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Handler fired in response to a Ready event.

fn deregister_shard<'life0, 'async_trait>( &'life0 self, shard_id: u32, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Handler fired in response to a disconnect, reconnection, or rebalance.

fn server_update<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, guild_id: SerenityGuild, endpoint: &'life1 Option<String>, token: &'life2 str, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Handler for VOICE_SERVER_UPDATE messages.

fn state_update<'life0, 'life1, 'async_trait>( &'life0 self, guild_id: SerenityGuild, voice_state: &'life1 VoiceState, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Handler for VOICE_STATE_UPDATE messages.