Struct TwitchIRCClient

pub struct TwitchIRCClient<T: Transport, L: LoginCredentials> { /* private fields */ }

A send-only handle to control the Twitch IRC Client.

Implementations

impl<T: Transport, L: LoginCredentials> TwitchIRCClient<T, L>

pub fn new( config: ClientConfig<L>, ) -> (UnboundedReceiver<ServerMessage>, TwitchIRCClient<T, L>)

Create a new client from the given configuration.

Note this method is not side-effect-free - a background task will be spawned as a result of calling this function.

impl<T: Transport, L: LoginCredentials> TwitchIRCClient<T, L>

pub async fn connect(&self)

Connect to Twitch IRC without joining any channels.

You typically do not need to call this method. This is only provided for the rare case that one would only want to receive incoming whispers without joining channels or ever sending messages out. If your application joins channels during startup, calling .connect() is superfluous, as the client will automatically open the necessary connections when you join channels or send messages.

pub async fn send_message(&self, message: IRCMessage) -> Result<(), Error<T, L>>

Send an arbitrary IRC message to one of the connections in the connection pool.

An error is returned in case the message could not be sent over the picked connection.

pub async fn privmsg( &self, channel_login: String, message: String, ) -> Result<(), Error<T, L>>

Send a PRIVMSG-type IRC message to a Twitch channel. The message can be a normal chat message or a chat command like /ban or similar. Note however that the usage of chat commands via IRC is deprecated and scheduled to be removed by Twitch for 2023-02-18.

If you want to just send a normal chat message, say() should be preferred since it prevents commands like /ban from accidentally being executed.

pub async fn say( &self, channel_login: String, message: String, ) -> Result<(), Error<T, L>>

Say a chat message in the given Twitch channel.

This method automatically prevents commands from being executed. For example say("a_channel", "/ban a_user") would not actually ban a user, instead it would send that exact message as a normal chat message instead.

No particular filtering is performed on the message. If the message is too long for chat, it will not be cut short or split into multiple messages (what happens is determined by the behaviour of the Twitch IRC server).

pub async fn me( &self, channel_login: String, message: String, ) -> Result<(), Error<T, L>>

Say a /me chat message in the given Twitch channel. These messages are usually shown in Twitch chat in italics or in the bot’s name color, and without the colon normally separating name and message, e.g.:

client.say("sodapoppin".to_owned(), "Hey guys!".to_owned());
// Displayed as: A_Cool_New_Bot: Hey guys!
client.me("sodapoppin".to_owned(), "is now leaving to grab a drink.".to_owned());
// Displayed as: *A_Cool_New_Bot is now leaving to grab a drink.*

This method automatically prevents commands from being executed. For example me("a_channel", "/ban a_user") would not actually ban a user, instead it would send that exact message as a normal chat message instead.

No particular filtering is performed on the message. If the message is too long for chat, it will not be cut short or split into multiple messages (what happens is determined by the behaviour of the Twitch IRC server).

pub async fn say_in_reply_to( &self, reply_to: &impl ReplyToMessage, message: String, ) -> Result<(), Error<T, L>>

Reply to a given message. The sent message is tagged to be in reply of the specified message, using that message’s unique ID. The message is of course also sent to same channel as the message that we are replying to.

This method automatically prevents commands from being executed. For example say_in_reply_to(a_message, "/ban a_user") would not actually ban a user, instead it would send that exact message as a normal chat message instead.

No particular filtering is performed on the message. If the message is too long for chat, it will not be cut short or split into multiple messages (what happens is determined by the behaviour of the Twitch IRC server).

The given parameter can be anything that implements ReplyToMessage, which can be one of the following:

• a &PrivmsgMessage
• a tuple (&str, &str) or (String, String), where the first member is the login name of the channel the message was sent to, and the second member is the ID of the message to reply to.

Note that even though UserNoticeMessage has a message_id, you can NOT reply to these messages or delete them. For this reason, ReplyToMessage is not implemented for UserNoticeMessage.

pub async fn me_in_reply_to( &self, reply_to: &impl ReplyToMessage, message: String, ) -> Result<(), Error<T, L>>

Reply to a given message with a /me message. The sent message is tagged to be in reply of the specified message, using that message’s unique ID. The message is of course also sent to same channel as the message that we are replying to.

See the documentation on the me() method for more details about what /me messages are.

This method automatically prevents commands from being executed. For example me_in_reply_to(a_message, "/ban a_user") would not actually ban a user, instead it would send that exact message as a normal chat message instead.

No particular filtering is performed on the message. If the message is too long for chat, it will not be cut short or split into multiple messages (what happens is determined by the behaviour of the Twitch IRC server).

The given parameter can be anything that implements ReplyToMessage, which can be one of the following:

• a &PrivmsgMessage
• a tuple (&str, &str) or (String, String), where the first member is the login name of the channel the message was sent to, and the second member is the ID of the message to reply to.

Note that even though UserNoticeMessage has a message_id, you can NOT reply to these messages or delete them. For this reason, ReplyToMessage is not implemented for UserNoticeMessage.

pub async fn ban( &self, channel_login: String, target_login: &str, reason: Option<&str>, ) -> Result<(), Error<T, L>>

👎Deprecated since 4.1.0: Usage of chat commands via IRC is deprecated and scheduled for removal by Twitch for 2023-02-18. See https://discuss.dev.twitch.tv/t/deprecation-of-chat-commands-through-irc/40486

Ban a user with an optional reason from the given Twitch channel.

Note that this will not throw an error if the target user is already banned, doesn’t exist or if the logged-in user does not have the required permission to ban the user. An error is only returned if something prevented the command from being sent over the wire.

pub async fn unban( &self, channel_login: String, target_login: &str, ) -> Result<(), Error<T, L>>

👎Deprecated since 4.1.0: Usage of chat commands via IRC is deprecated and scheduled for removal by Twitch for 2023-02-18. See https://discuss.dev.twitch.tv/t/deprecation-of-chat-commands-through-irc/40486

Unban a user from the given Twitch channel.

Note that this will not throw an error if the target user is not currently banned, doesn’t exist or if the logged-in user does not have the required permission to unban the user. An error is only returned if something prevented the command from being sent over the wire.

pub async fn timeout( &self, channel_login: String, target_login: &str, duration: Duration, reason: Option<&str>, ) -> Result<(), Error<T, L>>

👎Deprecated since 4.1.0: Usage of chat commands via IRC is deprecated and scheduled for removal by Twitch for 2023-02-18. See https://discuss.dev.twitch.tv/t/deprecation-of-chat-commands-through-irc/40486

Timeout a user in the given Twitch channel.

Note that this will not throw an error if the target user is banned, doesn’t exist or if the logged-in user does not have the required permission to timeout the user. An error is only returned if something prevented the command from being sent over the wire.

pub async fn untimeout( &self, channel_login: String, target_login: &str, ) -> Result<(), Error<T, L>>

👎Deprecated since 4.1.0: Usage of chat commands via IRC is deprecated and scheduled for removal by Twitch for 2023-02-18. See https://discuss.dev.twitch.tv/t/deprecation-of-chat-commands-through-irc/40486

Remove the timeout from a user in the given Twitch channel.

Note that this will not throw an error if the target user is banned, not currently timed out, doesn’t exist or if the logged-in user does not have the required permission to remove the timeout from the user. An error is only returned if something prevented the command from being sent over the wire.

pub fn join(&self, channel_login: String) -> Result<(), Error>

Join the given Twitch channel (When a channel is joined, the client will receive messages sent to it).

The client will internally ensure that there has always been at least an attempt to join this channel. However this does not necessarily mean the join is always successful.

If the given channel_login does not exist (or is suspended) then the IRC server will ignore the JOIN and you will not be joined to the given channel (what channel would you even expect to join if the channel does not exist?).

However, the client listens for a server-side confirmation to this JOIN command. If the server confirms that the JOIN was successful, then the client saves this information. This information can be queried using get_channel_status().

If you later issue another join() call, and the server previously confirmed the successful joining of channel_login, then no message will be sent out.

However if the server did not confirm the successful JOIN command previously, then the JOIN is attempted again.

You can use this mechanism to e.g. periodically re-try JOINing a given channel if joining to freshly created channels or freshly renamed channels is a concern in your application.

Another note on Twitch behaviour: If a channel gets suspended, the JOIN membership stays active as long as the connection with that JOIN membership stays active. For this reason, there is no special logic or handling required for when a channel gets suspended. (The JOIN membership in that channel will continue to count as confirmed for as long as the connection stays alive. If the connection fails, the “confirmed” status for that channel is reset, and the client will automatically attempt to re-join that channel on a different or new connection. Unless an answer is again received by the server, the join() will then make attempts again to join that channel.

Returns a validate::Error if the passed channel_login is of invalid format. Returns Ok(()) otherwise.

pub fn set_wanted_channels( &self, channels: HashSet<String>, ) -> Result<(), Error>

Instruct the client to only be connected to these channels. Channels currently joined but not in the given set are parted, and channels in the set that are not currently joined are joined.

For further semantics about join and parts, see the documentation for TwitchIRCClient::join.

Returns a validate::Error if the passed channel_login is of invalid format. Returns Ok(()) otherwise.

pub async fn get_channel_status(&self, channel_login: String) -> (bool, bool)

Query the client for what status a certain channel is in.

Returns two booleans: The first indicates whether a channel is wanted. This is true if the last operation for this channel was a join() method, or alternatively whether it was included in the set of channels in a set_wanted_channels call.

The second boolean indicates whether this channel is currently joined server-side. (This is purely based on JOIN and PART messages being received from the server).

Note that any combination of true and false is possible here.

For example, (true, false) could indicate that the JOIN message to join this channel is currently being sent or already sent, but no response confirming the JOIN has been received yet. Note this status can also mean that the server did not answer the JOIN request because the channel did not exist/was suspended or similar conditions.

(false, true) might on the other hand (similarly) that a PART message is sent but not answered yet by the server.

(true, true) confirms that the channel is currently successfully joined in a normal fashion.

(false, false) is returned for a channel that has not been joined previously at all or where a previous PART command has completed.

pub fn part(&self, channel_login: String)

Part (leave) a channel, to stop receiving messages sent to that channel.

This has the same semantics as join(). Similarly, a part() call will have no effect if the channel is not currently joined.

pub async fn ping(&self) -> Result<(), Error<T, L>>

Ping a random connection. This does not await the PONG response from Twitch. The future resolves once the PING command is sent to the wire. An error is returned in case the message could not be sent over the picked connection.

Trait Implementations

impl<T: Transport, L: LoginCredentials> Clone for TwitchIRCClient<T, L>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + Transport, L: Debug + LoginCredentials> Debug for TwitchIRCClient<T, L>

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

Formats the value using the given formatter.