Struct AsyncChannel 

pub struct AsyncChannel { /* private fields */ }

An asynchronous SSH channel, one of possibly many within a single SSH AsyncSession. Each channel represents a separate command, shell, SFTP session, X11 forwarding, or other SSH subsystem.

This struct is a thin wrapper around russh::Channel which provides access to async read/write streams (stdout/stderr/stdin) and async event handling Implements Deref to allow access to the underlying russh::ChannelWriteHalf.

Shutdown Lifecycle

During shutdown, events may be received in the following order. However this should not be relied upon, as the order may be different and none of these events are guaranteed to occur, except for Self::wait_close which will always happen last.

1. Self::recv_success_failure.
2. Self::recv_eof - Guarantees all stream data has been received, i.e. stdout/stderr will produce no more data. Channels may be closed without sending EOF; see this StackOverflow answer.
3. Self::recv_exit_status - The exit status of the command run, if applicable.
4. Self::wait_close - This channel is closed, no more events will occur.

Implementations

impl AsyncChannel

pub async fn sftp(&self) -> Result<SftpSession, SftpError>

Available on crate feature sftp only.

Starst an SFTP session on this channel.

Make sure this channel was opened with AsyncSession::open_sftp, or if not, make sure to request the SFTP subsystem before calling this:

channel.request_subsystem(true, "sftp").await.unwrap();

impl AsyncChannel

pub fn read_stream(&self, ext: Option<u32>) -> ReadStream

Returns the specified stream as a ReadStream.

Note that the returned stream will only receive data after this call, so call this before calling exec.

When this is called for the same ext more than once, the later call will disconnect the first.

pub fn stdout(&self) -> ReadStream

Returns stdout as a ReadStream.

Note that the returned stream will only receive data after this call, so call this before calling exec.

When this is called more than once, the later call will disconnect the first.

pub fn stderr(&self) -> ReadStream

Returns stderr as a ReadStream.

Note that the returned stream will only receive data after this call, so call this before calling exec.

When this is called more than once, the later call will disconnect the first.

pub fn write_stream(&self, ext: Option<u32>) -> impl AsyncWrite

Returns the specified stream as an impl AsyncWrite.

When this is called for the same ext more than once, writes to each may be interleaved.

pub fn stdin(&self) -> impl AsyncWrite

Returns stdin as an impl AsyncWrite.

When this is called more than once, writes to each may be interleaved.

pub fn recv_success_failure(&self) -> &Promise<bool>

Resolves when success or failure has been received, where true indicates success.

pub fn recv_eof(&self) -> &Promise<()>

Resolves when EOF has been received, indicating all stream data is complete.

At that point, any streams from Self::stdout/Self::stderr/Self::read_stream will return no additional data.

pub fn recv_exit_status(&self) -> &Promise<u32>

Resolves when the command exit status has been received.

pub async fn wait_close(&mut self)

Returns when the channel has been closed.

After this point, no more events will resolve.

pub fn is_closed(&self) -> bool

Returns if the channel has been closed. See Self::wait_close.

Methods from Deref<Target = ChannelWriteHalf<Msg>>

pub async fn writable_packet_size(&self) -> usize

Returns the min between the maximum packet size and the remaining window size in the channel.

pub fn id(&self) -> ChannelId

pub async fn request_pty( &self, want_reply: bool, term: &str, col_width: u32, row_height: u32, pix_width: u32, pix_height: u32, terminal_modes: &[(Pty, u32)], ) -> Result<(), Error>

Request a pseudo-terminal with the given characteristics.

pub async fn request_shell(&self, want_reply: bool) -> Result<(), Error>

Request a remote shell.

pub async fn exec<A>(&self, want_reply: bool, command: A) -> Result<(), Error>

where A: Into<Vec<u8>>,

Execute a remote program (will be passed to a shell). This can be used to implement scp (by calling a remote scp and tunneling to its standard input).

pub async fn signal(&self, signal: Sig) -> Result<(), Error>

Signal a remote process.

pub async fn request_subsystem<A>( &self, want_reply: bool, name: A, ) -> Result<(), Error>

where A: Into<String>,

Request the start of a subsystem with the given name.

pub async fn request_x11<A, B>( &self, want_reply: bool, single_connection: bool, x11_authentication_protocol: A, x11_authentication_cookie: B, x11_screen_number: u32, ) -> Result<(), Error>

where A: Into<String>, B: Into<String>,

Request X11 forwarding through an already opened X11 channel. See RFC4254 for security issues related to cookies.

pub async fn set_env<A, B>( &self, want_reply: bool, variable_name: A, variable_value: B, ) -> Result<(), Error>

where A: Into<String>, B: Into<String>,

Set a remote environment variable.

pub async fn window_change( &self, col_width: u32, row_height: u32, pix_width: u32, pix_height: u32, ) -> Result<(), Error>

Inform the server that our window size has changed.

pub async fn agent_forward(&self, want_reply: bool) -> Result<(), Error>

Inform the server that we will accept agent forwarding channels

pub async fn data<R>(&self, data: R) -> Result<(), Error>

where R: AsyncRead + Unpin,

Send data to a channel.

pub async fn extended_data<R>(&self, ext: u32, data: R) -> Result<(), Error>

where R: AsyncRead + Unpin,

Send data to a channel. The number of bytes added to the “sending pipeline” (to be processed by the event loop) is returned.

pub async fn eof(&self) -> Result<(), Error>

pub async fn exit_status(&self, exit_status: u32) -> Result<(), Error>

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

Request that the channel be closed.

pub fn make_writer(&self) -> impl AsyncWrite

Make a writer for the Channel to send ChannelMsg::Data through the AsyncWrite trait.

pub fn make_writer_ext(&self, ext: Option<u32>) -> impl AsyncWrite

Make a writer for the Channel to send ChannelMsg::Data or ChannelMsg::ExtendedData depending on the ext parameter, through the AsyncWrite trait.

Trait Implementations

impl Deref for AsyncChannel

type Target = ChannelWriteHalf<Msg>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl From<Channel<Msg>> for AsyncChannel

fn from(inner: Channel<Msg>) -> Self

Converts to this type from the input type.