sshkit v0.3.0 SSHKit.SSH.Channel View Source

Defines a SSHKit.SSH.Channel struct representing a connection channel.

A channel struct has the following fields:

  • connection - the underlying SSHKit.SSH.Connection
  • type - the type of the channel, i.e. :session
  • id - the unique channel id

Link to this section Summary

Functions

Adjusts the flow control window.

Closes an SSH channel.

Sends an EOF message on an open SSH channel.

Executes a command on the remote host.

Flushes any pending messages for the given channel.

Loops over channel messages until the channel is closed, or looping is stopped explicitly.

Opens a channel on an SSH connection.

Receive the next message on an open SSH channel.

Sends data across an open SSH channel.

Activates a subsystem on a channel.

Link to this section Functions

Adjusts the flow control window.

Returns :ok.

For more details, see :ssh_connection.adjust_window/3.

Closes an SSH channel.

Returns :ok.

For more details, see :ssh_connection.close/2.

Sends an EOF message on an open SSH channel.

Returns :ok or {:error, :closed}.

For more details, see :ssh_connection.send_eof/2.

Link to this function

exec(channel, command, timeout \\ :infinity)

View Source

Executes a command on the remote host.

Returns :success, :failure or {:error, reason}.

For more details, see :ssh_connection.exec/4.

Processing channel messages

loop/4 may be used to process any channel messages received as a result of executing command on the remote.

Link to this function

flush(channel, timeout \\ 0)

View Source

Flushes any pending messages for the given channel.

Returns :ok.

Link to this function

loop(channel, timeout \\ :infinity, acc, fun)

View Source

Loops over channel messages until the channel is closed, or looping is stopped explicitly.

Expects an accumulator on each call that determines how to proceed:

  1. {:cont, acc}

    The loop will wait for an inbound message. It will then pass the message and current acc to the looping function. fun's return value is the accumulator for the next cycle.

  2. {:cont, message, acc}

    Sends a message to the remote end of the channel before waiting for a message as outlined in the {:cont, acc} case above. message may be one of the following:

    • {0, data} or {1, data} - sends normal or stderr data to the remote
    • data - is a shortcut for {0, data}
    • :eof - sends EOF
  3. {:halt, acc}

    Terminates the loop, returning {:halted, acc}.

  4. {:suspend, acc}

    Suspends the loop, returning {:suspended, acc, continuation}. continuation is a function that accepts a new accumulator value and that, when called, will resume the loop.

timeout specifies the maximum wait time for receiving and sending individual messages.

Once the final {:closed, channel} message is received, the loop will terminate and return {:done, acc}. The channel will be closed if it has not been closed before.

Link to this function

open(connection, options \\ [])

View Source

Opens a channel on an SSH connection.

On success, returns {:ok, channel}, where channel is a Channel struct. Returns {:error, reason} if a failure occurs.

For more details, see :ssh_connection.session_channel/4.

Options

  • :timeout - defaults to :infinity
  • :initial_window_size - defaults to 128 KiB
  • :max_packet_size - defaults to 32 KiB
Link to this function

ptty(channel, options \\ [], timeout \\ :infinity)

View Source

Allocates PTTY.

Returns :success.

For more details, see :ssh_connection.ptty_alloc/4.

Link to this function

recv(channel, timeout \\ :infinity)

View Source

Receive the next message on an open SSH channel.

Returns {:ok, message} or {:error, :timeout}.

Only listens to messages from the channel specified as the first argument.

Messages

The message tuples returned by recv/3 correspond to the underlying Erlang channel messages with the channel id replaced by the SSHKit channel struct:

  • {:data, channel, type, data}
  • {:eof, channel}
  • {:exit_signal, channel, signal, msg, lang}
  • {:exit_status, channel, status}
  • {:closed, channel}

For more details, see :ssh_connection.

Link to this function

send(channel, type \\ 0, data, timeout \\ :infinity)

View Source

Sends data across an open SSH channel.

data may be an enumerable, e.g. a File.Stream or IO.Stream.

Returns :ok, {:error, :timeout} or {:error, :closed}.

For more details, see :ssh_connection.send/5.

Link to this function

subsystem(channel, subsystem, options \\ [])

View Source
subsystem(channel :: struct(), subsystem :: String.t(), options :: list()) ::
  :success | :failure | {:error, reason :: String.t()}

Activates a subsystem on a channel.

Returns :success, :failure or {:error, reason}.

For more details, see :ssh_connection.subsystem/4.