aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--lib/ssh/doc/src/ssh_connection.xml167
-rw-r--r--lib/ssh/src/ssh_connection.erl142
2 files changed, 171 insertions, 138 deletions
diff --git a/lib/ssh/doc/src/ssh_connection.xml b/lib/ssh/doc/src/ssh_connection.xml
index ea41ccf252..9fa1da659c 100644
--- a/lib/ssh/doc/src/ssh_connection.xml
+++ b/lib/ssh/doc/src/ssh_connection.xml
@@ -44,7 +44,7 @@
The Erlang format of thoose messages is
(see also <seealso marker="#type-event">below</seealso>):
</p>
- <p><c>{ssh_cm, </c><seealso marker="ssh:ssh#type-connection_ref">ssh:connection_ref()</seealso><c>, </c><seealso marker="#type-ssh_event_msg"><c>ssh_event_msg()</c></seealso><c>}</c>
+ <p><c>{ssh_cm, </c><seealso marker="ssh:ssh#type-connection_ref">ssh:connection_ref()</seealso><c>, </c><seealso marker="#type-channel_msg"><c>channel_msg()</c></seealso><c>}</c>
</p>
<p>
If the <seealso marker="ssh_client_channel">ssh_client_channel</seealso> behavior is used to
@@ -94,7 +94,7 @@
<datatype_title>SSH Connection Protocol: General</datatype_title>
<datatype>
<name name="event"/>
- <name name="ssh_event_msg"/>
+ <name name="channel_msg"/>
<desc>
<p>As mentioned in the introduction, the
<url href="https://tools.ietf.org/html/rfc4254">SSH Connection Protocol</url>
@@ -105,71 +105,39 @@
</desc>
</datatype>
- <datatype_title>SSH Connection Protocol: Data Events</datatype_title>
<datatype>
- <name name="data_event"/>
+ <name name="want_reply"/>
<desc>
+ <p>Messages that include a <c>WantReply</c> expect the channel handling
+ process to call <seealso marker="ssh_connection#reply_request-4">
+ ssh_connection:reply_request/4</seealso>
+ with the boolean value of <c>WantReply</c> as the second argument.</p>
</desc>
</datatype>
+
+ <datatype_title>Data Transfer (RFC 4254, section 5.2)</datatype_title>
<datatype>
- <name name="data_data_event"/>
+ <name name="data_ch_msg"/>
<desc>
<p>Data has arrived on the channel. This event is sent as a result of calling
<seealso marker="ssh_connection#send-3"> ssh_connection:send/[3,4,5]</seealso>.
</p>
</desc>
</datatype>
+
+
+ <datatype_title>Closing a Channel (RFC 4254, section 5.3)</datatype_title>
<datatype>
- <name name="data_eof_event"/>
+ <name name="eof_ch_msg"/>
<desc>
<p>Indicates that the other side sends no more data. This event is sent as a result of calling
<seealso marker="ssh_connection#send_eof-2"> ssh_connection:send_eof/2</seealso>.
</p>
</desc>
</datatype>
-
- <datatype_title>SSH Connection Protocol: Status Events</datatype_title>
- <datatype>
- <name name="status_event"/>
- <desc>
- </desc>
- </datatype>
-
<datatype>
- <name name="status_signal_event"/>
- <desc>
- <p>A signal can be delivered to the remote process/service
- using the following message. Some systems do not support
- signals, in which case they are to ignore this message. There is
- currently no function to generate this event as the signals
- referred to are on OS-level and not something generated by an
- Erlang program.</p>
- </desc>
- </datatype>
-
- <datatype>
- <name name="status_exit_signal_event"/>
- <desc>
- <p>A remote execution can terminate violently because of a signal.
- Then this message can be received. For details on valid string
- values, see <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url>
- Section 6.10, which shows a special case of these signals.</p>
- </desc>
- </datatype>
- <datatype>
- <name name="status_exit_status_event"/>
- <desc>
- <p>When the command running at the other end terminates, the
- following message can be sent to return the exit status of the
- command. A zero <c>exit_status</c> usually means that the command
- terminated successfully. This event is sent as a result of calling
- <seealso marker="ssh_connection#exit_status-3">
- ssh_connection:exit_status/3</seealso>.</p>
- </desc>
- </datatype>
- <datatype>
- <name name="status_closed_event"/>
+ <name name="closed_ch_msg"/>
<desc>
<p>This event is sent as a result of calling
<seealso marker="ssh_connection#close-2">ssh_connection:close/2</seealso>.
@@ -178,33 +146,11 @@
</desc>
</datatype>
- <datatype_title>SSH Connection Protocol: Terminal Events</datatype_title>
- <datatype>
- <name name="terminal_event"/>
- <desc>
- <p>Channels implementing a shell and command execution on the
- server side are to handle the following messages that can be sent by client-
- channel processes.</p>
-
- <p>Events that include a <c>WantReply</c> expect the event handling
- process to call <seealso marker="ssh_connection#reply_request-4">
- ssh_connection:reply_request/4</seealso>
- with the boolean value of <c>WantReply</c> as the second argument.</p>
- </desc>
- </datatype>
-
- <datatype>
- <name name="terminal_env_event"/>
- <desc>
- <p>Environment variables can be passed to the shell/command
- to be started later. This event is sent as a result of calling <seealso
- marker="ssh_connection#setenv-5"> ssh_connection:setenv/5</seealso>.
- </p>
- </desc>
- </datatype>
+ <datatype_title>Requesting a Pseudo-Terminal (RFC 4254, section 6.2)</datatype_title>
<datatype>
- <name name="terminal_pty_event"/>
+ <name name="pty_ch_msg"/>
+ <name name="term_mode"/>
<desc>
<p>A pseudo-terminal has been requested for the
session. <c>Terminal</c> is the value of the TERM environment
@@ -214,7 +160,7 @@
drawable area of the window. <c>Opcode</c> in the
<c>TerminalModes</c> list is the mnemonic name, represented
as a lowercase Erlang atom, defined in
- <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url>, Section 8.
+ <url href="https://tools.ietf.org/html/rfc4254#section-8">RFC 4254</url>, Section 8.
It can also be an <c>Opcode</c> if the mnemonic name is not listed in the
RFC. Example: <c>OP code: 53, mnemonic name ECHO erlang atom:
echo</c>. This event is sent as a result of calling <seealso
@@ -222,8 +168,22 @@
</desc>
</datatype>
+
+ <datatype_title>Environment Variable Passing (RFC 4254, section 6.4)</datatype_title>
<datatype>
- <name name="terminal_shell_event"/>
+ <name name="env_ch_msg"/>
+ <desc>
+ <p>Environment variables can be passed to the shell/command
+ to be started later. This event is sent as a result of calling <seealso
+ marker="ssh_connection#setenv-5"> ssh_connection:setenv/5</seealso>.
+ </p>
+ </desc>
+ </datatype>
+
+
+ <datatype_title>Starting a Shell or Command (RFC 4254, section 6.5)</datatype_title>
+ <datatype>
+ <name name="shell_ch_msg"/>
<desc>
<p>This message requests that the user default shell
is started at the other end. This event is sent as a result of calling
@@ -231,9 +191,20 @@
</p>
</desc>
</datatype>
+ <datatype>
+ <name name="exec_ch_msg"/>
+ <desc>
+ <p>This message requests that the server starts
+ execution of the given command. This event is sent as a result of calling <seealso
+ marker="ssh_connection#exec-4">ssh_connection:exec/4 </seealso>.
+ </p>
+ </desc>
+ </datatype>
+
+ <datatype_title>Window Dimension Change Message (RFC 4254, section 6.7)</datatype_title>
<datatype>
- <name name="terminal_window_change_event"/>
+ <name name="window_change_ch_msg"/>
<desc>
<p>When the window (terminal) size changes on the client
side, it <em>can</em> send a message to the server side to inform it of
@@ -241,13 +212,39 @@
</desc>
</datatype>
+ <datatype_title>Signals (RFC 4254, section 6.9)</datatype_title>
<datatype>
- <name name="terminal_exec_event"/>
+ <name name="signal_ch_msg"/>
<desc>
- <p>This message requests that the server starts
- execution of the given command. This event is sent as a result of calling <seealso
- marker="ssh_connection#exec-4">ssh_connection:exec/4 </seealso>.
- </p>
+ <p>A signal can be delivered to the remote process/service
+ using the following message. Some systems do not support
+ signals, in which case they are to ignore this message. There is
+ currently no function to generate this event as the signals
+ referred to are on OS-level and not something generated by an
+ Erlang program.</p>
+ </desc>
+ </datatype>
+
+
+ <datatype_title>Returning Exit Status (RFC 4254, section 6.10)</datatype_title>
+ <datatype>
+ <name name="exit_status_ch_msg"/>
+ <desc>
+ <p>When the command running at the other end terminates, the
+ following message can be sent to return the exit status of the
+ command. A zero <c>exit_status</c> usually means that the command
+ terminated successfully. This event is sent as a result of calling
+ <seealso marker="ssh_connection#exit_status-3">
+ ssh_connection:exit_status/3</seealso>.</p>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="exit_signal_ch_msg"/>
+ <desc>
+ <p>A remote execution can terminate violently because of a signal.
+ Then this message can be received. For details on valid string
+ values, see <url href="https://tools.ietf.org/html/rfc4254#section-6.10">RFC 4254</url>
+ Section 6.10, which shows a special case of these signals.</p>
</desc>
</datatype>
@@ -316,22 +313,22 @@
</taglist-->
<taglist>
- <tag>N x <seealso marker="#type-data_data_event">data message(s)</seealso></tag>
+ <tag>N x <seealso marker="#type-data_ch_msg">data message(s)</seealso></tag>
<item><p>The result of executing the command can be only one line
or thousands of lines depending on the command.</p></item>
- <tag>0 or 1 x <seealso marker="#type-data_eof_event">eof message</seealso></tag>
+ <tag>0 or 1 x <seealso marker="#type-eof_ch_msg">eof message</seealso></tag>
<item><p>Indicates that no more data is to be sent.</p></item>
- <tag>0 or 1 x <seealso marker="#type-status_exit_signal_event">exit signal message</seealso></tag>
+ <tag>0 or 1 x <seealso marker="#type-exit_signal_ch_msg">exit signal message</seealso></tag>
<item><p>Not all systems send signals. For details on valid string
values, see RFC 4254, Section 6.10</p></item>
- <tag>0 or 1 x <seealso marker="#type-status_exit_status_event">exit status message</seealso></tag>
+ <tag>0 or 1 x <seealso marker="#type-exit_status_ch_msg">exit status message</seealso></tag>
<item><p>It is recommended by the SSH Connection Protocol to send this
message, but that is not always the case.</p></item>
- <tag>1 x <seealso marker="#type-status_closed_event">closed status message</seealso></tag>
+ <tag>1 x <seealso marker="#type-closed_ch_msg">closed status message</seealso></tag>
<item><p>Indicates that the <c>ssh_client_channel</c> started for the
execution of the command has now been shut down.</p></item>
</taglist>
diff --git a/lib/ssh/src/ssh_connection.erl b/lib/ssh/src/ssh_connection.erl
index 1e54be2a16..e6de9dd054 100644
--- a/lib/ssh/src/ssh_connection.erl
+++ b/lib/ssh/src/ssh_connection.erl
@@ -78,61 +78,97 @@
%%% The SSH Connection Protocol
-export_type([event/0,
- ssh_event_msg/0,
- data_event/0,
- data_data_event/0,
- data_eof_event/0,
- status_event/0,
- status_signal_event/0,
- status_exit_signal_event/0,
- status_exit_status_event/0,
- status_closed_event/0,
- terminal_event/0,
- terminal_env_event/0,
- terminal_pty_event/0,
- terminal_shell_event/0,
- terminal_window_change_event/0,
- terminal_exec_event/0
+ channel_msg/0,
+ want_reply/0,
+ data_ch_msg/0,
+ eof_ch_msg/0,
+ signal_ch_msg/0,
+ exit_signal_ch_msg/0,
+ exit_status_ch_msg/0,
+ closed_ch_msg/0,
+ env_ch_msg/0,
+ pty_ch_msg/0,
+ shell_ch_msg/0,
+ window_change_ch_msg/0,
+ exec_ch_msg/0
]).
--type event() :: {ssh_cm, ssh:connection_ref(), ssh_event_msg()}.
--type ssh_event_msg() :: data_event() | status_event() | terminal_event() .
-
--type data_event() :: data_data_event()
- | data_eof_event() .
--type data_data_event() :: {data, ssh:channel_id(), ssh_data_type_code(), Data :: binary()} .
--type data_eof_event() :: {eof, ssh:channel_id()} .
-
-
--type status_event() :: status_signal_event()
- | status_exit_signal_event()
- | status_exit_status_event()
- | status_closed_event() .
-
--type status_signal_event() :: {signal, ssh:channel_id(), SignalName::string()} .
--type status_exit_signal_event() :: {exit_signal, ssh:channel_id(),
- ExitSignal :: string(),
- ErrorMsg ::string(),
- LanguageString :: string()} .
--type status_exit_status_event() :: {exit_status, ssh:channel_id(), ExitStatus :: integer()} .
--type status_closed_event() :: {closed, ssh:channel_id()} .
-
--type terminal_event() :: terminal_env_event()
- | terminal_pty_event()
- | terminal_shell_event()
- | terminal_window_change_event()
- | terminal_exec_event() .
-
--type terminal_env_event() :: {env, ssh:channel_id(), WantReply :: boolean(), Var ::string(), Value :: string()} .
--type terminal_pty_event() :: {pty, ssh:channel_id(),
- WantReply :: boolean(),
- {Terminal :: string(), CharWidth :: integer(), RowHeight :: integer(), PixelWidth :: integer(), PixelHeight :: integer(),
- TerminalModes :: [{Opcode :: atom() | integer(),
- Value :: integer()}]}} .
--type terminal_shell_event() :: {shell, WantReply :: boolean()} .
--type terminal_window_change_event() :: {window_change, ssh:channel_id(), CharWidth :: integer(),
- RowHeight :: integer(), PixWidth :: integer(), PixHeight :: integer()} .
--type terminal_exec_event() :: {exec, ssh:channel_id(), WantReply :: boolean(), Cmd :: string()} .
+-type event() :: {ssh_cm, ssh:connection_ref(), channel_msg()}.
+-type channel_msg() :: data_ch_msg()
+ | eof_ch_msg()
+ | closed_ch_msg()
+ | pty_ch_msg()
+ | env_ch_msg()
+ | shell_ch_msg()
+ | exec_ch_msg()
+ | signal_ch_msg()
+ | window_change_ch_msg()
+ | exit_status_ch_msg()
+ | exit_signal_ch_msg()
+ .
+
+-type want_reply() :: boolean().
+
+-type data_ch_msg() :: {data,
+ ssh:channel_id(),
+ ssh_data_type_code(),
+ Data :: binary()
+ } .
+-type eof_ch_msg() :: {eof,
+ ssh:channel_id()
+ } .
+-type signal_ch_msg() :: {signal,
+ ssh:channel_id(),
+ SignalName :: string()
+ } .
+-type exit_signal_ch_msg() :: {exit_signal, ssh:channel_id(),
+ ExitSignal :: string(),
+ ErrorMsg :: string(),
+ LanguageString :: string()} .
+-type exit_status_ch_msg() :: {exit_status,
+ ssh:channel_id(),
+ ExitStatus :: non_neg_integer()
+ } .
+-type closed_ch_msg() :: {closed,
+ ssh:channel_id()
+ } .
+-type env_ch_msg() :: {env,
+ ssh:channel_id(),
+ want_reply(),
+ Var :: string(),
+ Value :: string()
+ } .
+-type pty_ch_msg() :: {pty,
+ ssh:channel_id(),
+ want_reply(),
+ {Terminal :: string(),
+ CharWidth :: non_neg_integer(),
+ RowHeight :: non_neg_integer(),
+ PixelWidth :: non_neg_integer(),
+ PixelHeight :: non_neg_integer(),
+ TerminalModes :: [term_mode()]
+ }
+ } .
+
+-type term_mode() :: {Opcode :: atom() | byte(),
+ Value :: non_neg_integer()} .
+
+-type shell_ch_msg() :: {shell,
+ ssh:channel_id(),
+ want_reply()
+ } .
+-type window_change_ch_msg() :: {window_change,
+ ssh:channel_id(),
+ CharWidth :: non_neg_integer(),
+ RowHeight :: non_neg_integer(),
+ PixelWidth :: non_neg_integer(),
+ PixelHeight :: non_neg_integer()
+ } .
+-type exec_ch_msg() :: {exec,
+ ssh:channel_id(),
+ want_reply(),
+ Command :: string()
+ } .
%%% This function is soley to convince all
%%% checks that the type event() exists...