Struct irc::client::server::IrcServer

pub struct IrcServer { /* 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 Server and ServerExt traits that provide methods of communicating with the server after connection. Cloning an IrcServer 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.

Methods

impl IrcServer

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

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

Example

let server = IrcServer::new("config.toml").unwrap(); 

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

Creates a new IRC server connection 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 IrcServer::new_future instead.

Example

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

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

Creates a new IRC server connection from the specified configuration and on the event loop corresponding to the given handle. This can be used to set up a number of IrcServers 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.

Example

let mut reactor = Core::new().unwrap();
let future = IrcServer::new_future(reactor.handle(), &config).unwrap(); 
// immediate connection errors (like no internet) will turn up here...
let server = reactor.run(future).unwrap();
// runtime errors (like disconnections and so forth) will turn up here...
reactor.run(server.stream().for_each(move |irc_msg| {
  // processing messages works like usual
  process_msg(&server, irc_msg)
})).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 IrcServer

fn clone(&self) -> IrcServer

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Server for IrcServer

fn config(&self) -> &Config

Gets the configuration being used with this Server.

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

Sends a Command to this Server. 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 ServerExt. They capture a lot of the more repetitive aspects of sending messages.

fn stream(&self) -> ServerStream

Gets a stream of incoming messages from the Server. 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.