Struct Channel

pub struct Channel { /* private fields */ }

A channel represents a portion of an SSH connection on which data can be read and written.

Channels denote all of SCP uploads and downloads, shell sessions, remote process executions, and other general-purpose sessions. Each channel implements the Reader and Writer traits to send and receive data. Whether or not I/O operations are blocking is mandated by the blocking flag on a channel’s corresponding Session.

You may clone a Channel to obtain another handle to the same underlying channel, but note that all clones will share the same underlying SSH session and will be subject to the same blocking behavior. For more details on the implications of cloning and blocking operations, refer to the Session documentation.

Implementations

impl Channel

pub fn setenv(&mut self, var: &str, val: &str) -> Result<(), Error>

Set an environment variable in the remote channel’s process space.

Note that this does not make sense for all channel types and may be ignored by the server despite returning success.

pub fn request_pty( &mut self, term: &str, mode: Option<PtyModes>, dim: Option<(u32, u32, u32, u32)>, ) -> Result<(), Error>

Request a PTY on an established channel.

Note that this does not make sense for all channel types and may be ignored by the server despite returning success.

The dimensions argument is a tuple of (width, height, width_px, height_px)

The mode parameter is optional and specifies modes to apply to the pty. Use the PtyModes type construct these modes. A contrived example of this is below:

let mut mode = ssh2::PtyModes::new();
// Set the interrupt character to CTRL-C (ASCII 3: ETX).
// This is typically the default, but we're showing how to
// set a relatable option for the sake of example!
mode.set_character(ssh2::PtyModeOpcode::VINTR, Some(3 as char));

pub fn request_pty_size( &mut self, width: u32, height: u32, width_px: Option<u32>, height_px: Option<u32>, ) -> Result<(), Error>

Request that the PTY size be changed to the specified size. width and height are the number of character cells, and you may optionally include the size specified in pixels.

pub fn request_auth_agent_forwarding(&mut self) -> Result<(), Error>

Requests that the remote host start an authentication agent; if successful requests to that agent will be forwarded from the server back to the local authentication agent on the client side.

Note that some hosts are configured to disallow agent forwarding, and that even if enabled, there is a possibility that starting the agent on the remote system can fail.

pub fn exec(&mut self, command: &str) -> Result<(), Error>

Execute a command

An execution is one of the standard process services defined by the SSH2 protocol.

Example

let mut channel = session.channel_session().unwrap();
channel.exec("ls").unwrap();
let mut s = String::new();
channel.read_to_string(&mut s).unwrap();
println!("{}", s);

pub fn shell(&mut self) -> Result<(), Error>

Start a shell

A shell is one of the standard process services defined by the SSH2 protocol.

pub fn subsystem(&mut self, system: &str) -> Result<(), Error>

Request a subsystem be started.

A subsystem is one of the standard process services defined by the SSH2 protocol.

pub fn process_startup( &mut self, request: &str, message: Option<&str>, ) -> Result<(), Error>

Initiate a request on a session type channel.

The SSH2 protocol currently defines shell, exec, and subsystem as standard process services.

pub fn stderr(&self) -> Stream

Get a handle to the stderr stream of this channel.

The returned handle implements the Read and Write traits.

pub fn stream(&self, stream_id: i32) -> Stream

Get a handle to a particular stream for this channel.

The returned handle implements the Read and Write traits.

Groups of substreams may be flushed by passing one of the following constants and then calling flush().

• FLUSH_EXTENDED_DATA - Flush all extended data substreams
• FLUSH_ALL - Flush all substreams

pub fn handle_extended_data(&mut self, mode: ExtendedData) -> Result<(), Error>

Change how extended data (such as stderr) is handled

pub fn exit_status(&self) -> Result<i32, Error>

Returns the exit code raised by the process running on the remote host at the other end of the named channel.

Note that the exit status may not be available if the remote end has not yet set its status to closed.

pub fn exit_signal(&self) -> Result<ExitSignal, Error>

Get the remote exit signal.

pub fn read_window(&self) -> ReadWindow

Check the status of the read window.

pub fn write_window(&self) -> WriteWindow

Check the status of the write window.

pub fn adjust_receive_window( &mut self, adjust: u64, force: bool, ) -> Result<u64, Error>

Adjust the receive window for a channel by adjustment bytes.

If the amount to be adjusted is less than the minimum adjustment and force is false, the adjustment amount will be queued for a later packet.

This function returns the new size of the receive window (as understood by remote end) on success.

pub fn eof(&self) -> bool

Check if the remote host has sent an EOF status for the channel. Take care: the EOF status is for the entire channel which can be confusing because the reading from the channel reads only the stdout stream. unread, buffered, stderr data will cause eof() to return false.

pub fn send_eof(&mut self) -> Result<(), Error>

Tell the remote host that no further data will be sent on the specified channel.

Processes typically interpret this as a closed stdin descriptor.

pub fn wait_eof(&mut self) -> Result<(), Error>

Wait for the remote end to send EOF. Note that unread buffered stdout and stderr will cause this function to return Ok(()) without waiting. You should call the eof() function after calling this to check the status of the channel.

pub fn close(&mut self) -> Result<(), Error>

Close an active data channel.

In practice this means sending an SSH_MSG_CLOSE packet to the remote host which serves as instruction that no further data will be sent to it. The remote host may still send data back until it sends its own close message in response.

To wait for the remote end to close its connection as well, follow this command with wait_close

pub fn wait_close(&mut self) -> Result<(), Error>

Enter a temporary blocking state until the remote host closes the named channel.

Typically sent after close in order to examine the exit status.

Trait Implementations

impl Clone for Channel

fn clone(&self) -> Channel

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Read for Channel

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl Write for Channel

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

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.