Struct irc::client::IrcClient

pub struct IrcClient { /* fields omitted */ }

The canonical implementation of a connection to an IRC server.

The type itself provides a number of methods to create new connections, but most of the API surface is in the form of the Client and ClientExt traits that provide methods of communicating with the server after connection. Cloning an IrcClient is relatively cheap, as it's equivalent to cloning a single Arc. This may be useful for setting up multiple threads with access to one connection.

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

Methods

impl IrcClient

fn new<P: AsRef<Path>>(config: P) -> Result<IrcClient>

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

Example

let client = IrcClient::new("config.toml").unwrap();

fn from_config(config: Config) -> Result<IrcClient>

Creates a new IrcClient from the specified configuration, connecting immediately. Due to current design limitations, error handling here is somewhat limited. In particular, failed connections will cause the program to panic because the connection attempt is made on a freshly created thread. If you need to avoid this behavior and handle errors more gracefully, it is recommended that you use an IrcReactor instead.

Example

let config = Config {
  nickname: Some("example".to_owned()),
  server: Some("irc.example.com".to_owned()),
  .. Default::default()
};
let client = IrcClient::from_config(config).unwrap();

fn new_future(handle: Handle, config: &Config) -> Result<IrcClientFuture>

Creates a Future of an IrcClient from the specified configuration and on the event loop corresponding to the given handle. This can be used to set up a number of IrcClients 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.

Proper usage requires familiarity with tokio and futures. You can find more information in the crate documentation for tokio-core or futures. Additionally, you can find detailed tutorials on using both libraries on the tokio website. An easy to use abstraction that does not require this knowledge is available via IrcReactors.

Example

let mut reactor = Core::new().unwrap();
let future = IrcClient::new_future(reactor.handle(), &config).unwrap();
// immediate connection errors (like no internet) will turn up here...
let PackedIrcClient(client, future) = reactor.run(future).unwrap();
// runtime errors (like disconnections and so forth) will turn up here...
reactor.run(client.stream().for_each(move |irc_msg| {
  // processing messages works like usual
  process_msg(&client, irc_msg)
}).join(future)).unwrap();

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.

Trait Implementations

impl Clone for IrcClient

fn clone(&self) -> IrcClient

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for IrcClient

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Client for IrcClient

fn config(&self) -> &Config

Gets the configuration being used with this Client.

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

Sends a Command as this Client. This is the core primitive for sending messages to the server. In practice, it's often more pleasant (and more idiomatic) to use the functions defined on ClientExt. They capture a lot of the more repetitive aspects of sending messages.

fn stream(&self) -> 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 IRC bots should be able to get by using only for_each_incoming to handle received messages. You can find some examples of more complex setups using stream in the GitHub repository.

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

Gets a list of currently joined channels. This will be None if tracking is disabled altogether via the nochanlists feature.

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 nochanlists feature is enabled, this function will return None.

fn for_each_incoming<F>(&self, f: F) -> Result<()> where
    F: FnMut(Message), 

Blocks on the stream, running the given function on each incoming message as they arrive.