Struct irc::client::Client

pub struct Client { /* private fields */ }

The canonical implementation of a connection to an IRC server.

For a full example usage, see [irc::client].

Implementations

impl Client

pub async fn new<P: AsRef<Path>>(config: P) -> Result<Client>

Creates a new Client from the configuration at the specified path, connecting immediately. This function is short-hand for loading the configuration and then calling Client::from_config and consequently inherits its behaviors.

Example

let client = Client::new("config.toml").await?;

pub async fn from_config(config: Config) -> Result<Client>

Creates a Future of an Client from the specified configuration and on the event loop corresponding to the given handle. This can be used to set up a number of Clients on a single, shared event loop. It can also be used to take more control over execution and error handling. Connection will not occur until the event loop is run.

pub fn outgoing(&mut self) -> Option<Outgoing>

Take the outgoing future in order to drive it yourself.

Must be called before stream if you intend to drive this future yourself.

pub fn sender(&self) -> Sender

Get access to a thread-safe sender that can be used with the client.

pub fn stream(&mut self) -> Result<ClientStream>

Gets a stream of incoming messages from the Client’s connection. This is only necessary when trying to set up more complex clients, and requires use of the futures crate. Most You can find some examples of setups using stream in the GitHub repository.

Note: The stream can only be returned once. Subsequent attempts will cause a panic.

pub fn list_channels(&self) -> Option<Vec<String>>

Gets a list of currently joined channels. This will be None if tracking is disabled altogether by disabling the channel-lists feature.

pub fn list_users(&self, chan: &str) -> Option<Vec<User>>

Gets a list of [Users] in the specified channel. If the specified channel hasn’t been joined or the channel-lists feature is disabled, this function will return None.

For best results, be sure to request multi-prefix support from the server. This will allow for more accurate tracking of user rank (e.g. oper, half-op, etc.).

Requesting multi-prefix support

use irc::proto::caps::Capability;

client.send_cap_req(&[Capability::MultiPrefix])?;
client.identify()?;

pub fn current_nickname(&self) -> &str

Gets the current nickname in use. This may be the primary username set in the configuration, or it could be any of the alternative nicknames listed as well. As a result, this is the preferred way to refer to the client’s nickname.

pub fn send<M: Into<Message>>(&self, msg: M) -> Result<()>

Sends a Command as this Client. This is the core primitive for sending messages to the server.

Example

client.send(Command::NICK("example".to_owned())).unwrap();
client.send(Command::USER("user".to_owned(), "0".to_owned(), "name".to_owned())).unwrap();

pub fn identify(&self) -> Result<()>

Sends a CAP END, NICK and USER to identify.

pub fn send_mode<S, T>(&self, target: S, modes: &[Mode<T>]) -> Result<()>

where S: Display, T: ModeType,

Changes the modes for the specified target.

pub fn send_join<S>(&self, chanlist: S) -> Result<()>

where S: Display,

Joins the specified channel or chanlist.

pub fn send_join_with_keys<S1, S2>( &self, chanlist: S1, keylist: S2 ) -> Result<()>

where S1: Display, S2: Display,

Joins the specified channel or chanlist using the specified key or keylist.

pub fn send_notice<S1, S2>(&self, target: S1, message: S2) -> Result<()>

where S1: Display, S2: Display,

Sends a notice to the specified target.

pub fn send_cap_ls(&self, version: NegotiationVersion) -> Result<()>

Sends a request for a list of server capabilities for a specific IRCv3 version.

pub fn send_cap_req(&self, extensions: &[Capability]) -> Result<()>

Sends an IRCv3 capabilities request for the specified extensions.

pub fn send_sasl<S: Display>(&self, data: S) -> Result<()>

Sends a SASL AUTHENTICATE message with the specified data.

pub fn send_sasl_plain(&self) -> Result<()>

Sends a SASL AUTHENTICATE request to use the PLAIN mechanism.

pub fn send_sasl_external(&self) -> Result<()>

Sends a SASL AUTHENTICATE request to use the EXTERNAL mechanism.

pub fn send_sasl_abort(&self) -> Result<()>

Sends a SASL AUTHENTICATE request to abort authentication.

pub fn send_pong<S>(&self, msg: S) -> Result<()>

where S: Display,

Sends a PONG with the specified message.

pub fn send_part<S>(&self, chanlist: S) -> Result<()>

where S: Display,

Parts the specified channel or chanlist.

pub fn send_oper<S1, S2>(&self, username: S1, password: S2) -> Result<()>

where S1: Display, S2: Display,

Attempts to oper up using the specified username and password.

pub fn send_privmsg<S1, S2>(&self, target: S1, message: S2) -> Result<()>

where S1: Display, S2: Display,

Sends a message to the specified target. If the message contains IRC newlines (\r\n), it will automatically be split and sent as multiple separate PRIVMSGs to the specified target. If you absolutely must avoid this behavior, you can do client.send(PRIVMSG(target, message)) directly.

pub fn send_topic<S1, S2>(&self, channel: S1, topic: S2) -> Result<()>

where S1: Display, S2: Display,

Sets the topic of a channel or requests the current one. If topic is an empty string, it won’t be included in the message.

pub fn send_kill<S1, S2>(&self, target: S1, message: S2) -> Result<()>

where S1: Display, S2: Display,

Kills the target with the provided message.

pub fn send_kick<S1, S2, S3>( &self, chanlist: S1, nicklist: S2, message: S3 ) -> Result<()>

where S1: Display, S2: Display, S3: Display,

Kicks the listed nicknames from the listed channels with a comment. If message is an empty string, it won’t be included in the message.

pub fn send_samode<S1, S2, S3>( &self, target: S1, mode: S2, modeparams: S3 ) -> Result<()>

where S1: Display, S2: Display, S3: Display,

Changes the mode of the target by force. If modeparams is an empty string, it won’t be included in the message.

pub fn send_sanick<S1, S2>(&self, old_nick: S1, new_nick: S2) -> Result<()>

where S1: Display, S2: Display,

Forces a user to change from the old nickname to the new nickname.

pub fn send_invite<S1, S2>(&self, nick: S1, chan: S2) -> Result<()>

where S1: Display, S2: Display,

Invites a user to the specified channel.

pub fn send_quit<S>(&self, msg: S) -> Result<()>

where S: Display,

Quits the server entirely with a message. This defaults to Powered by Rust. if none is specified.

pub fn send_ctcp<S1, S2>(&self, target: S1, msg: S2) -> Result<()>

where S1: Display, S2: Display,

Sends a CTCP-escaped message to the specified target. This requires the CTCP feature to be enabled.

pub fn send_action<S1, S2>(&self, target: S1, msg: S2) -> Result<()>

where S1: Display, S2: Display,

Sends an action command to the specified target. This requires the CTCP feature to be enabled.

pub fn send_finger<S>(&self, target: S) -> Result<()>

where S: Display,

Sends a finger request to the specified target. This requires the CTCP feature to be enabled.

pub fn send_version<S>(&self, target: S) -> Result<()>

where S: Display,

Sends a version request to the specified target. This requires the CTCP feature to be enabled.

pub fn send_source<S>(&self, target: S) -> Result<()>

where S: Display,

Sends a source request to the specified target. This requires the CTCP feature to be enabled.

pub fn send_user_info<S>(&self, target: S) -> Result<()>

where S: Display,

Sends a user info request to the specified target. This requires the CTCP feature to be enabled.

pub fn send_ctcp_ping<S>(&self, target: S) -> Result<()>

where S: Display,

Sends a finger request to the specified target. This requires the CTCP feature to be enabled.

pub fn send_time<S>(&self, target: S) -> Result<()>

where S: Display,

Sends a time request to the specified target. This requires the CTCP feature to be enabled.

Trait Implementations

impl Debug for Client

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

Formats the value using the given formatter.