Struct telnet::Telnet

pub struct Telnet { /* fields omitted */ }

A telnet connection to a remote host.

Examples

use telnet::Telnet;

let mut connection = Telnet::connect(("127.0.0.1", 23), 256)
        .expect("Couldn't connect to the server...");
loop {
    let event = connection.read().expect("Read Error");
    println!("{:?}", event);
}

Implementations

impl Telnet

pub fn connect<A: ToSocketAddrs>(addr: A, buf_size: usize) -> Result<Telnet>

Opens a telnet connection to a remote host using a TcpStream.

addr is an address of the remote host. Note that a remote host usually opens port 23 for a Telnet connection. buf_size is a size of the underlying buffer for processing the data read from the remote host.

Examples

use telnet::Telnet;

let connection = Telnet::connect(("127.0.0.1", 23), 256)
        .expect("Couldn't connect to the server...");

Errors

• Tcp connection failure

pub fn connect_timeout(
    addr: &SocketAddr,
    buf_size: usize,
    timeout: Duration
) -> Result<Telnet>

Opens a telnet connection to a remote host using a TcpStream with a timeout Duration. Uses a TcpStream::connect_timeout under the hood and so can only be passed a single address of type SocketAddr, and passing a zero Duration results in an error.

Examples

use telnet::Telnet;
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use std::str::FromStr;
use std::time::Duration;
let address = SocketAddr::new(IpAddr::V4(Ipv4Addr::from_str("127.0.0.1")
                                .expect("Invalid address")), 23);
let telnet = Telnet::connect_timeout(&address, 256, Duration::from_secs(2))
                                .expect("Couldn't connect to the server...");

Errors

• Tcp connection failure
• I/O timeout error

pub fn from_stream(stream: Box<dyn Stream>, buf_size: usize) -> Telnet

Open a telnet connection to a remote host using a generic stream.

Communication will be made with the host using stream. buf_size is the size of the underlying buffer for processing data from the host.

Use this version of the constructor if you want to provide your own stream, for example if you want to mock out the remote host for testing purposes, or want to wrap the data with TLS encryption.

pub fn read(&mut self) -> Result<Event>

Reads an Event.

If there was not any queued Event, it would read a chunk of data into its buffer, extract any telnet command in the message, and queue all processed results. Otherwise, it would take a queued Event without reading data from TcpStream.

Examples

use telnet::Telnet;

let mut connection = Telnet::connect(("127.0.0.1", 23), 256)
        .expect("Couldn't connect to the server...");
let event = connection.read().expect("Read Error");
println!("{:?}", event);

Errors

• Read stream fails
• Set stream settings fails

pub fn read_timeout(&mut self, timeout: Duration) -> Result<Event>

Reads an Event, but the waiting time cannot exceed a given Duration.

This method is similar to Telnet::read, but with a time limitation. If the given time was reached, it would return Event::TimedOut.

Examples

use std::time::Duration;
use telnet::Telnet;

let mut connection = Telnet::connect(("127.0.0.1", 23), 256)
        .expect("Couldn't connect to the server...");
let event = connection.read_timeout(Duration::new(5, 0)).expect("Read Error");
println!("{:?}", event);

Errors

• Set stream settings fails
• Read stream fails

pub fn read_nonblocking(&mut self) -> Result<Event>

Reads an Event. Returns immediately if there was no queued event and nothing to read.

This method is a non-blocking version of Telnet::read. If there was no more data, it would return Event::NoData.

Examples

use telnet::Telnet;

let mut connection = Telnet::connect(("127.0.0.1", 23), 256)
        .expect("Couldn't connect to the server...");
let event = connection.read_nonblocking().expect("Read Error");
println!("{:?}", event);

Errors

• Set stream settings fails
• Read stream fails

pub fn write(&mut self, data: &[u8]) -> Result<usize>

Writes a given data block to the remote host. It will double any IAC byte.

Examples

use telnet::Telnet;

let mut connection = Telnet::connect(("127.0.0.1", 23), 256)
        .expect("Couldn't connect to the server...");
let buffer: [u8; 4] = [83, 76, 77, 84];
connection.write(&buffer).expect("Write Error");

Errors

• Write to stream fails

pub fn negotiate(
    &mut self,
    action: &Action,
    opt: TelnetOption
) -> Result<(), TelnetError>

Negotiates a telnet option with the remote host.

Examples

use telnet::{Telnet, Action, TelnetOption};

let mut connection = Telnet::connect(("127.0.0.1", 23), 256)
        .expect("Couldn't connect to the server...");
connection.negotiate(&Action::Will, TelnetOption::Echo);

Errors

• TelnetError::NegotiationErr if negotiation fails

pub fn subnegotiate(
    &mut self,
    opt: TelnetOption,
    data: &[u8]
) -> Result<(), TelnetError>

Send data for sub-negotiation with the remote host.

Examples

use telnet::{Telnet, Action, TelnetOption};

let mut connection = Telnet::connect(("127.0.0.1", 23), 256)
        .expect("Couldn't connect to the server...");
connection.negotiate(&Action::Do, TelnetOption::TTYPE);
let data: [u8; 1] = [1];
connection.subnegotiate(TelnetOption::TTYPE, &data);

Errors

• TelnetError::SubnegotiationErr if subnegotiation fails