diff options
| -rw-r--r-- | lib/ssh/doc/src/ssh_connection.xml | 167 | ||||
| -rw-r--r-- | lib/ssh/src/ssh_connection.erl | 142 |
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... |