From e7abd910a9cd94677bbcb19cdf5a2bdc2cb83279 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Wed, 7 Aug 2019 17:17:54 +0200 Subject: ssh: The ssh_connection documentation is now generated --- lib/ssh/src/ssh_connection.erl | 160 ++++++++++++++++++++++++++++++++++------- 1 file changed, 136 insertions(+), 24 deletions(-) (limited to 'lib/ssh/src/ssh_connection.erl') diff --git a/lib/ssh/src/ssh_connection.erl b/lib/ssh/src/ssh_connection.erl index 83f85b1d8e..1e54be2a16 100644 --- a/lib/ssh/src/ssh_connection.erl +++ b/lib/ssh/src/ssh_connection.erl @@ -67,6 +67,79 @@ -type connection_ref() :: ssh:connection_ref(). -type channel_id() :: ssh:channel_id(). +-type req_status() :: success | failure . +-type reason() :: closed | timeout . + +-type result() :: req_status() | {error, reason()} . + +-type ssh_data_type_code() :: non_neg_integer(). % Only 0 and 1 are used + + +%%% 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 + ]). + +-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()} . + +%%% This function is soley to convince all +%%% checks that the type event() exists... +-export([dummy/1]). +-spec dummy(event()) -> false. +dummy(_) -> false. + %%-------------------------------------------------------------------- %%% API %%-------------------------------------------------------------------- @@ -77,14 +150,21 @@ %% application, a system command, or some built-in subsystem. %% -------------------------------------------------------------------- --spec session_channel(connection_ref(), timeout()) -> - {ok, channel_id()} | {error, timeout | closed}. +-spec session_channel(ConnectionRef, Timeout) -> Result when + ConnectionRef :: ssh:connection_ref(), + Timeout :: timeout(), + Result :: {ok, ssh:channel_id()} | {error, reason()} . session_channel(ConnectionHandler, Timeout) -> session_channel(ConnectionHandler, ?DEFAULT_WINDOW_SIZE, ?DEFAULT_PACKET_SIZE, Timeout). --spec session_channel(connection_ref(), integer(), integer(), timeout()) -> - {ok, channel_id()} | {error, timeout | closed}. + +-spec session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize, Timeout) -> Result when + ConnectionRef :: ssh:connection_ref(), + InitialWindowSize :: pos_integer(), + MaxPacketSize :: pos_integer(), + Timeout :: timeout(), + Result :: {ok, ssh:channel_id()} | {error, reason()} . session_channel(ConnectionHandler, InitialWindowSize, MaxPacketSize, Timeout) -> case ssh_connection_handler:open_channel(ConnectionHandler, "session", <<>>, @@ -100,8 +180,11 @@ session_channel(ConnectionHandler, InitialWindowSize, MaxPacketSize, Timeout) -> %% Description: Will request that the server start the %% execution of the given command. %%-------------------------------------------------------------------- --spec exec(connection_ref(), channel_id(), string(), timeout()) -> - success | failure | {error, timeout | closed}. +-spec exec(ConnectionRef, ChannelId, Command, Timeout) -> result() when + ConnectionRef :: ssh:connection_ref(), + ChannelId :: ssh:channel_id(), + Command :: string(), + Timeout :: timeout(). exec(ConnectionHandler, ChannelId, Command, TimeOut) -> ssh_connection_handler:request(ConnectionHandler, self(), ChannelId, "exec", @@ -112,8 +195,10 @@ exec(ConnectionHandler, ChannelId, Command, TimeOut) -> %% defined in /etc/passwd in UNIX systems) be started at the other %% end. %%-------------------------------------------------------------------- --spec shell(connection_ref(), channel_id()) -> - ok | success | failure | {error, timeout}. +-spec shell(ConnectionRef, ChannelId) -> Result when + ConnectionRef :: ssh:connection_ref(), + ChannelId :: ssh:channel_id(), + Result :: ok | success | failure | {error, timeout} . shell(ConnectionHandler, ChannelId) -> ssh_connection_handler:request(ConnectionHandler, self(), ChannelId, @@ -122,8 +207,11 @@ shell(ConnectionHandler, ChannelId) -> %% %% Description: Executes a predefined subsystem. %%-------------------------------------------------------------------- --spec subsystem(connection_ref(), channel_id(), string(), timeout()) -> - success | failure | {error, timeout | closed}. +-spec subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> result() when + ConnectionRef :: ssh:connection_ref(), + ChannelId :: ssh:channel_id(), + Subsystem :: string(), + Timeout :: timeout(). subsystem(ConnectionHandler, ChannelId, SubSystem, TimeOut) -> ssh_connection_handler:request(ConnectionHandler, self(), @@ -134,12 +222,13 @@ subsystem(ConnectionHandler, ChannelId, SubSystem, TimeOut) -> %%-------------------------------------------------------------------- -spec send(connection_ref(), channel_id(), iodata()) -> ok | {error, timeout | closed}. + send(ConnectionHandler, ChannelId, Data) -> send(ConnectionHandler, ChannelId, 0, Data, infinity). --spec send(connection_ref(), channel_id(), integer()| iodata(), timeout() | iodata()) -> - ok | {error, timeout | closed}. +-spec send(connection_ref(), channel_id(), iodata(), timeout()) -> ok | {error, reason()}; + (connection_ref(), channel_id(), ssh_data_type_code(), iodata()) -> ok | {error, reason()}. send(ConnectionHandler, ChannelId, Data, TimeOut) when is_integer(TimeOut) -> send(ConnectionHandler, ChannelId, 0, Data, TimeOut); @@ -151,14 +240,15 @@ send(ConnectionHandler, ChannelId, Type, Data) -> send(ConnectionHandler, ChannelId, Type, Data, infinity). --spec send(connection_ref(), channel_id(), integer(), iodata(), timeout()) -> - ok | {error, timeout | closed}. +-spec send(connection_ref(), channel_id(), ssh_data_type_code(), iodata(), timeout()) -> ok | {error, reason()}. send(ConnectionHandler, ChannelId, Type, Data, TimeOut) -> ssh_connection_handler:send(ConnectionHandler, ChannelId, Type, Data, TimeOut). %%-------------------------------------------------------------------- --spec send_eof(connection_ref(), channel_id()) -> ok | {error, closed}. +-spec send_eof(ConnectionRef, ChannelId) -> ok | {error, closed} when + ConnectionRef :: ssh:connection_ref(), + ChannelId :: ssh:channel_id(). %% %% %% Description: Sends eof on the channel . @@ -167,7 +257,10 @@ send_eof(ConnectionHandler, Channel) -> ssh_connection_handler:send_eof(ConnectionHandler, Channel). %%-------------------------------------------------------------------- --spec adjust_window(connection_ref(), channel_id(), integer()) -> ok. +-spec adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok when + ConnectionRef :: ssh:connection_ref(), + ChannelId :: ssh:channel_id(), + NumOfBytes :: integer(). %% %% %% Description: Adjusts the ssh flowcontrol window. @@ -176,8 +269,12 @@ adjust_window(ConnectionHandler, Channel, Bytes) -> ssh_connection_handler:adjust_window(ConnectionHandler, Channel, Bytes). %%-------------------------------------------------------------------- --spec setenv(connection_ref(), channel_id(), string(), string(), timeout()) -> - success | failure | {error, timeout | closed}. +-spec setenv(ConnectionRef, ChannelId, Var, Value, Timeout) -> result() when + ConnectionRef :: ssh:connection_ref(), + ChannelId :: ssh:channel_id(), + Var :: string(), + Value :: string(), + Timeout :: timeout(). %% %% %% Description: Environment variables may be passed to the shell/command to be @@ -189,7 +286,9 @@ setenv(ConnectionHandler, ChannelId, Var, Value, TimeOut) -> %%-------------------------------------------------------------------- --spec close(connection_ref(), channel_id()) -> ok. +-spec close(ConnectionRef, ChannelId) -> ok when + ConnectionRef :: ssh:connection_ref(), + ChannelId :: ssh:channel_id(). %% %% %% Description: Sends a close message on the channel . @@ -198,7 +297,11 @@ close(ConnectionHandler, ChannelId) -> ssh_connection_handler:close(ConnectionHandler, ChannelId). %%-------------------------------------------------------------------- --spec reply_request(connection_ref(), boolean(), success | failure, channel_id()) -> ok. +-spec reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok when + ConnectionRef :: ssh:connection_ref(), + WantReply :: boolean(), + Status :: req_status(), + ChannelId :: ssh:channel_id(). %% %% %% Description: Send status replies to requests that want such replies. @@ -211,15 +314,20 @@ reply_request(_,false, _, _) -> %%-------------------------------------------------------------------- %% Description: Sends a ssh connection protocol pty_req. %%-------------------------------------------------------------------- --spec ptty_alloc(connection_ref(), channel_id(), proplists:proplist()) -> - success | failure | {error, timeout}. +-spec ptty_alloc(ConnectionRef, ChannelId, Options) -> result() when + ConnectionRef :: ssh:connection_ref(), + ChannelId :: ssh:channel_id(), + Options :: proplists:proplist(). ptty_alloc(ConnectionHandler, Channel, Options) -> ptty_alloc(ConnectionHandler, Channel, Options, infinity). --spec ptty_alloc(connection_ref(), channel_id(), proplists:proplist(), timeout()) -> - success | failure | {error, timeout | closed}. +-spec ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> result() when + ConnectionRef :: ssh:connection_ref(), + ChannelId :: ssh:channel_id(), + Options :: proplists:proplist(), + Timeout :: timeout(). ptty_alloc(ConnectionHandler, Channel, Options0, TimeOut) -> TermData = backwards_compatible(Options0, []), % FIXME @@ -252,6 +360,10 @@ signal(ConnectionHandler, Channel, Sig) -> "signal", false, [?string(Sig)], 0). +-spec exit_status(ConnectionRef, ChannelId, Status) -> ok when + ConnectionRef :: ssh:connection_ref(), + ChannelId :: ssh:channel_id(), + Status :: integer(). exit_status(ConnectionHandler, Channel, Status) -> ssh_connection_handler:request(ConnectionHandler, Channel, "exit-status", false, [?uint32(Status)], 0). -- cgit v1.2.3 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/src/ssh_connection.erl | 142 ++++++++++++++++++++++++++--------------- 1 file changed, 89 insertions(+), 53 deletions(-) (limited to 'lib/ssh/src/ssh_connection.erl') 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