From 21b50e6bc78f26dd103ca2df1da51f9e1b3b5147 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Mon, 12 Aug 2019 15:30:22 +0200 Subject: ssh: change type names --- lib/ssh/doc/src/ssh_connection.xml | 167 ++++++++++++++++++------------------- 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 below):

-

{ssh_cm, ssh:connection_ref(), ssh_event_msg()} +

{ssh_cm, ssh:connection_ref(), channel_msg()}

If the ssh_client_channel behavior is used to @@ -94,7 +94,7 @@ SSH Connection Protocol: General - +

As mentioned in the introduction, the SSH Connection Protocol @@ -105,71 +105,39 @@ - SSH Connection Protocol: Data Events - + +

Messages that include a WantReply expect the channel handling + process to call + ssh_connection:reply_request/4 + with the boolean value of WantReply as the second argument.

+ + Data Transfer (RFC 4254, section 5.2) - +

Data has arrived on the channel. This event is sent as a result of calling ssh_connection:send/[3,4,5].

+ + + Closing a Channel (RFC 4254, section 5.3) - +

Indicates that the other side sends no more data. This event is sent as a result of calling ssh_connection:send_eof/2.

- - SSH Connection Protocol: Status Events - - - - - - - - -

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.

- - - - - - -

A remote execution can terminate violently because of a signal. - Then this message can be received. For details on valid string - values, see RFC 4254 - Section 6.10, which shows a special case of these signals.

- - - - - -

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 exit_status usually means that the command - terminated successfully. This event is sent as a result of calling - - ssh_connection:exit_status/3.

- - - - +

This event is sent as a result of calling ssh_connection:close/2. @@ -178,33 +146,11 @@ - SSH Connection Protocol: Terminal Events - - - -

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.

- -

Events that include a WantReply expect the event handling - process to call - ssh_connection:reply_request/4 - with the boolean value of WantReply as the second argument.

- - - - - - -

Environment variables can be passed to the shell/command - to be started later. This event is sent as a result of calling ssh_connection:setenv/5. -

- - + Requesting a Pseudo-Terminal (RFC 4254, section 6.2) - + +

A pseudo-terminal has been requested for the session. Terminal is the value of the TERM environment @@ -214,7 +160,7 @@ drawable area of the window. Opcode in the TerminalModes list is the mnemonic name, represented as a lowercase Erlang atom, defined in - RFC 4254, Section 8. + RFC 4254, Section 8. It can also be an Opcode if the mnemonic name is not listed in the RFC. Example: OP code: 53, mnemonic name ECHO erlang atom: echo. This event is sent as a result of calling + + Environment Variable Passing (RFC 4254, section 6.4) - + + +

Environment variables can be passed to the shell/command + to be started later. This event is sent as a result of calling ssh_connection:setenv/5. +

+ + + + + Starting a Shell or Command (RFC 4254, section 6.5) + +

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 @@

+ + + +

This message requests that the server starts + execution of the given command. This event is sent as a result of calling ssh_connection:exec/4 . +

+ + + + Window Dimension Change Message (RFC 4254, section 6.7) - +

When the window (terminal) size changes on the client side, it can send a message to the server side to inform it of @@ -241,13 +212,39 @@ + Signals (RFC 4254, section 6.9) - + -

This message requests that the server starts - execution of the given command. This event is sent as a result of calling ssh_connection:exec/4 . -

+

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.

+ + + + + Returning Exit Status (RFC 4254, section 6.10) + + + +

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 exit_status usually means that the command + terminated successfully. This event is sent as a result of calling + + ssh_connection:exit_status/3.

+ + + + + +

A remote execution can terminate violently because of a signal. + Then this message can be received. For details on valid string + values, see RFC 4254 + Section 6.10, which shows a special case of these signals.

 @@ -316,22 +313,22 @@ - N x data message(s) + N x data message(s)

The result of executing the command can be only one line or thousands of lines depending on the command.

 - 0 or 1 x eof message + 0 or 1 x eof message

Indicates that no more data is to be sent.

 - 0 or 1 x exit signal message + 0 or 1 x exit signal message

Not all systems send signals. For details on valid string values, see RFC 4254, Section 6.10

 - 0 or 1 x exit status message + 0 or 1 x exit status message

It is recommended by the SSH Connection Protocol to send this message, but that is not always the case.

 - 1 x closed status message + 1 x closed status message

Indicates that the ssh_client_channel started for the execution of the command has now been shut down.

 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... -- cgit v1.2.3