Struct twitch_irc::TwitchIRCClient

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

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.

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 say_in_response(
    &self,
    channel_login: String,
    message: String,
    reply_to_id: Option<String>
) -> Result<(), Error<T, L>>

Say a chat message in the given Twitch channel, but send it as a response to another message if reply_to_id is specified.

Behaves the same as say() when reply_to_id is None, but tags the original message and it's sender if specified.

pub async fn reply_to_privmsg(
    &self,
    message: String,
    reply_to: &PrivmsgMessage
) -> Result<(), Error<T, L>>

Replies to a given PrivmsgMessage, tagging the original message and it's sender.

Similarly to say(), this method strips the message of executing commands, but does not filter out messages which are too long. Refer to say() for the exact behaviour.

pub fn join(&self, channel_login: String)

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.

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

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.

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>

pub fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.