查看源代码 ssh_connection (ssh v5.2.5)
此模块提供 API 函数，用于向 SSH 通道的另一端发送 SSH 连接协议事件。
SSH 连接协议 (RFC 4254) 由客户端和服务器（即 SSH 通道）使用，以通过 SSH 连接进行通信。此模块中的 API 函数发送 SSH 连接协议事件，这些事件作为消息被远程通道接收，处理远程通道。这些消息的 Erlang 格式为（另请参阅下文）
{ssh_cm, ssh:connection_ref/0 , channel_msg/0 }
如果使用 ssh_client_channel 行为来实现通道进程，则这些消息由 handle_ssh_msg/2 处理。
概要
类型：通用
如引言所述，SSH 连接协议事件作为消息处理。当编写一个不使用 ssh_client_channel 行为支持的通道处理进程时，该进程必须处理这些消息。
包含 WantReply 的消息期望通道处理进程使用 WantReply 的布尔值作为第二个参数调用 ssh_connection:reply_request/4。
类型：数据传输
数据已到达通道。此事件是调用 ssh_connection:send/3,4,5 的结果。
类型：关闭通道
此事件是调用 ssh_connection:close/2 的结果。此事件的处理和发送都由 ssh_client_channel 行为负责。
指示另一端不再发送数据。此事件是调用 ssh_connection:send_eof/2 的结果。
类型：伪终端
已为会话请求伪终端。Terminal 是 TERM 环境变量的值，即 vt100。必须忽略零维度参数。字符/行维度将覆盖像素维度（当非零时）。像素维度是指窗口的可绘制区域。TerminalModes 列表中的 Opcode 是助记名称，表示为小写的 Erlang 原子，在 RFC 4254 第 8 节中定义。如果助记名称未在 RFC 中列出，它也可以是 Opcode。例如：OP 代码：53，助记名称 ECHO Erlang 原子：echo。此事件是调用 ssh_connection:ptty_alloc/4 的结果。
类型：环境变量
环境变量可以传递给稍后启动的 shell/命令。此事件是调用 ssh_connection:setenv/5 的结果。
类型：Shell 或命令
此消息请求服务器开始执行给定的命令。此事件是调用 ssh_connection:exec/4 的结果。
此消息请求在另一端启动用户默认的 shell。此事件是调用 ssh_connection:shell/2 的结果。
类型：窗口更改
当客户端的窗口（终端）大小发生更改时，它可以向服务器端发送消息，告知其新的尺寸。没有 API 函数会生成此事件。
类型：信号
可以使用以下消息将信号传递给远程进程/服务。某些系统不支持信号，在这种情况下，它们将忽略此消息。目前没有函数生成此事件，因为所指的信号是在操作系统级别，而不是由 Erlang 程序生成的。
类型：退出状态
由于信号，远程执行可能会暴力终止。然后可以接收此消息。有关有效字符串值的详细信息，请参阅 RFC 4254 第 6.10 节，其中显示了这些信号的特殊情况。
当另一端运行的命令终止时，可以发送以下消息以返回命令的退出状态。零 exit_status 通常表示命令成功终止。此事件是调用 ssh_connection:exit_status/3 的结果。
类型
调用的结果。
请求的状态。对应于 RFC 4254 第 5.4 节中的 SSH_MSG_CHANNEL_SUCCESS 和 SSH_MSG_CHANNEL_FAILURE 值。
有效值是 0（“正常”）和 1（“stderr”），请参阅 RFC 4254 第 5.2 节。
函数
调整 SSH 流控制窗口。这应由客户端和服务器端的通道进程完成。
服务器或客户端通道进程可以选择通过发送关闭事件来关闭其会话。
由客户端通道进程调用，以请求服务器开始执行给定的命令。结果是根据以下模式的多个消息。最后一个消息是通道关闭消息，因为 exec 请求是一次性执行，在完成后会关闭通道。
由服务器通道进程调用，以将命令的退出状态发送到客户端。
发送 SSH 连接协议 pty_req，以分配伪终端。由 SSH 客户端进程调用。
向请求者已声明它需要状态报告（即 WantReply = true）的请求发送状态回复。如果 WantReply 为 false，则调用此函数将变为“空操作”。在处理包含 WantReply 布尔值的 SSH 连接协议消息时调用。
根据输入参数，等效于下面指定的 send/5 调用之一。
由客户端和服务器通道进程调用，以相互发送数据。
在通道 ChannelId 上发送 EOF。
为 SSH 会话打开通道。从此函数返回的通道 ID 是用作此模块中其他函数输入的 ID。
可以在启动 shell/命令之前传递环境变量。由客户端通道进程调用。
由客户端通道进程调用，以请求在服务器端执行用户默认的 shell（通常在 Unix 系统中的 /etc/passwd 中定义）。
由客户端通道进程调用，以请求在服务器上执行预定义的子系统。
类型：通用
-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().
如引言所述，SSH 连接协议事件作为消息处理。当编写一个不使用 ssh_client_channel 行为支持的通道处理进程时，该进程必须处理这些消息。
-type event() :: {ssh_cm, ssh:connection_ref(), channel_msg()}.
-type want_reply() :: boolean().
包含 WantReply 的消息期望通道处理进程使用 WantReply 的布尔值作为第二个参数调用 ssh_connection:reply_request/4。
类型：数据传输
-type data_ch_msg() :: {data, ssh:channel_id(), ssh_data_type_code(), Data :: binary()}.
数据已到达通道。此事件是调用 ssh_connection:send/3,4,5 的结果。
类型：关闭通道
-type closed_ch_msg() :: {closed, ssh:channel_id()}.
此事件是调用 ssh_connection:close/2 的结果。此事件的处理和发送都由 ssh_client_channel 行为负责。
-type eof_ch_msg() :: {eof, ssh:channel_id()}.
指示另一端不再发送数据。此事件是调用 ssh_connection:send_eof/2 的结果。
类型：伪终端
-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()}.
已为会话请求伪终端。Terminal 是 TERM 环境变量的值，即 vt100。必须忽略零维度参数。字符/行维度将覆盖像素维度（当非零时）。像素维度是指窗口的可绘制区域。TerminalModes 列表中的 Opcode 是助记名称，表示为小写的 Erlang 原子，在 RFC 4254 第 8 节中定义。如果助记名称未在 RFC 中列出，它也可以是 Opcode。例如：OP 代码：53，助记名称 ECHO Erlang 原子：echo。此事件是调用 ssh_connection:ptty_alloc/4 的结果。
类型：环境变量
-type env_ch_msg() :: {env, ssh:channel_id(), want_reply(), Var :: string(), Value :: string()}.
环境变量可以传递给稍后启动的 shell/命令。此事件是调用 ssh_connection:setenv/5 的结果。
类型：Shell 或命令
-type exec_ch_msg() :: {exec, ssh:channel_id(), want_reply(), Command :: string()}.
此消息请求服务器开始执行给定的命令。此事件是调用 ssh_connection:exec/4 的结果。
-type shell_ch_msg() :: {shell, ssh:channel_id(), want_reply()}.
此消息请求在另一端启动用户默认的 shell。此事件是调用 ssh_connection:shell/2 的结果。
类型：窗口更改
-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()}.
当客户端的窗口（终端）大小发生更改时，它可以向服务器端发送消息，告知其新的尺寸。没有 API 函数会生成此事件。
类型：信号
-type signal_ch_msg() :: {signal, ssh:channel_id(), SignalName :: string()}.
可以使用以下消息将信号传递给远程进程/服务。某些系统不支持信号，在这种情况下，它们将忽略此消息。目前没有函数生成此事件，因为所指的信号是在操作系统级别，而不是由 Erlang 程序生成的。
类型：退出状态
-type exit_signal_ch_msg() :: {exit_signal, ssh:channel_id(), ExitSignal :: string(), ErrorMsg :: string(), LanguageString :: string()}.
由于信号，远程执行可能会暴力终止。然后可以接收此消息。有关有效字符串值的详细信息，请参阅 RFC 4254 第 6.10 节，其中显示了这些信号的特殊情况。
-type exit_status_ch_msg() :: {exit_status, ssh:channel_id(), ExitStatus :: non_neg_integer()}.
当另一端运行的命令终止时，可以发送以下消息以返回命令的退出状态。零 exit_status 通常表示命令成功终止。此事件是调用 ssh_connection:exit_status/3 的结果。
类型
-type channel_id() :: ssh:channel_id().
-type connection_ref() :: ssh:connection_ref().
-type reason() :: closed | timeout.
调用的结果。
如果请求到达对等节点，并且被处理，且响应到达请求节点，则 req_status/0 是对等节点报告的状态。
如果不是，则 reason/0 指示出了什么问题。
closed- 表示在尝试发送请求时，通道或连接已关闭。timeout- 表示操作超过了时间限制。
-type req_status() :: success | failure.
请求的状态。对应于 RFC 4254 第 5.4 节中的 SSH_MSG_CHANNEL_SUCCESS 和 SSH_MSG_CHANNEL_FAILURE 值。
-type result() :: req_status() | {error, reason()}.
-type ssh_data_type_code() :: non_neg_integer().
有效值是 0（“正常”）和 1（“stderr”），请参阅 RFC 4254 第 5.2 节。
函数
-spec adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok when ConnectionRef :: ssh:connection_ref(), ChannelId :: ssh:channel_id(), NumOfBytes :: integer().
调整 SSH 流控制窗口。这应由客户端和服务器端的通道进程完成。
注意
使用
ssh_client_channel行为实现的通道通常不需要调用此函数，因为流量控制由该行为处理。每次回调 handle_ssh_msg/2 在处理通道数据后返回时，该行为都会调整窗口。
-spec close(ConnectionRef, ChannelId) -> ok when ConnectionRef :: ssh:connection_ref(), ChannelId :: ssh:channel_id().
服务器或客户端通道进程可以选择通过发送关闭事件来关闭其会话。
注意
当通道终止时，
ssh_client_channel行为会调用此函数，请参阅ssh_client_channel。因此，使用该行为实现的通道不应显式调用此函数。
-spec exec(ConnectionRef, ChannelId, Command, Timeout) -> result() when ConnectionRef :: ssh:connection_ref(), ChannelId :: ssh:channel_id(), Command :: string(), Timeout :: timeout().
由客户端通道进程调用，以请求服务器开始执行给定的命令。结果是根据以下模式的多个消息。最后一个消息是通道关闭消息，因为 exec 请求是一次性执行，在完成后会关闭通道。
N x 数据消息 - 执行命令的结果可能只有一行，也可能是数千行，具体取决于命令。
0 或 1 x eof 消息 - 表示不再发送数据。
0 或 1 x 退出信号消息 - 并非所有系统都发送信号。有关有效字符串值的详细信息，请参阅 RFC 4254 第 6.10 节。
0 或 1 x 退出状态消息 - SSH 连接协议建议发送此消息，但并非总是如此。
1 x 关闭状态消息 - 表示为执行命令启动的
ssh_client_channel现在已关闭。
有关示例，请参阅用户指南中关于 一次性执行 的章节。
-spec exit_status(ConnectionRef, ChannelId, Status) -> ok when ConnectionRef :: ssh:connection_ref(), ChannelId :: ssh:channel_id(), Status :: integer().
由服务器通道进程调用，以将命令的退出状态发送到客户端。
-spec ptty_alloc(ConnectionRef, ChannelId, Options) -> result() when ConnectionRef :: ssh:connection_ref(), ChannelId :: ssh:channel_id(), Options :: proplists:proplist().
等效于 ptty_alloc/4。
-spec ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> result() when ConnectionRef :: ssh:connection_ref(), ChannelId :: ssh:channel_id(), Options :: proplists:proplist(), Timeout :: timeout().
发送 SSH 连接协议 pty_req，以分配伪终端。由 SSH 客户端进程调用。
选项
{term, string()} - 默认为 os:getenv("TERM")，如果未定义，则默认为 vt100。
{width, integer()} - 如果未定义
pixel_width，则默认为 80。{height, integer()} - 如果未定义
pixel_height，则默认为 24。{pixel_width, integer()} - 如果定义了
width，则忽略此选项。{pixel_height, integer()} - 如果定义了
height，则忽略此选项。{pty_opts, [{posix_atom(), integer()}]} - 该选项可以为空列表。否则，请参阅 RFC 4254 第 8 节中可能的 POSIX 名称。
-spec reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok when ConnectionRef :: ssh:connection_ref(), WantReply :: boolean(), Status :: req_status(), ChannelId :: ssh:channel_id().
向请求者已声明它需要状态报告（即 WantReply = true）的请求发送状态回复。如果 WantReply 为 false，则调用此函数将变为“空操作”。在处理包含 WantReply 布尔值的 SSH 连接协议消息时调用。
-spec send(connection_ref(), channel_id(), iodata()) -> ok | {error, reason()}.
等效于 send/5。
-spec send(connection_ref(), channel_id(), iodata(), timeout()) -> ok | {error, reason()}; (connection_ref(), channel_id(), ssh_data_type_code(), iodata()) -> ok | {error, reason()}.
根据输入参数，等效于下面指定的 send/5 调用之一。
如果使用整数类型的 TimeOut 调用，则等同于 send(ConnectionRef, ChannelId, 0, Data, TimeOut)。
如果使用无穷原子类型的 TimeOut 调用，则等同于 send(ConnectionRef, ChannelId, 0, Data, infinity)。
如果使用不是整数或无穷原子类型的最后一个参数调用，则等同于 send(ConnectionRef, ChannelId, Type, Data, infinity)。
-spec send(connection_ref(), channel_id(), ssh_data_type_code(), iodata(), timeout()) -> ok | {error, reason()}.
由客户端和服务器通道进程调用，以相互发送数据。
函数 subsystem/4 和后续的 send/3,4,5 调用必须在同一个进程中执行。
-spec send_eof(ConnectionRef, ChannelId) -> ok | {error, closed} when ConnectionRef :: ssh:connection_ref(), ChannelId :: ssh:channel_id().
在通道 ChannelId 上发送 EOF。
-spec session_channel(ConnectionRef, Timeout) -> Result when ConnectionRef :: ssh:connection_ref(), Timeout :: timeout(), Result :: {ok, ssh:channel_id()} | {error, reason()}.
等效于 session_channel/4。
-spec session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize, Timeout) -> Result when ConnectionRef :: ssh:connection_ref(), InitialWindowSize :: pos_integer() | undefined, MaxPacketSize :: pos_integer() | undefined, Timeout :: timeout(), Result :: {ok, ssh:channel_id()} | {error, reason()}.
为 SSH 会话打开通道。从此函数返回的通道 ID 是用作此模块中其他函数输入的 ID。
-spec setenv(ConnectionRef, ChannelId, Var, Value, Timeout) -> success when ConnectionRef :: ssh:connection_ref(), ChannelId :: ssh:channel_id(), Var :: string(), Value :: string(), Timeout :: timeout().
可以在启动 shell/命令之前传递环境变量。由客户端通道进程调用。
-spec shell(ConnectionRef, ChannelId) -> Result when ConnectionRef :: ssh:connection_ref(), ChannelId :: ssh:channel_id(), Result :: ok | success | failure | {error, timeout}.
由客户端通道进程调用，以请求在服务器端执行用户默认的 shell（通常在 Unix 系统中的 /etc/passwd 中定义）。
注意：与此模块中的其他函数不同，返回值是 ok 而不是 success。这是一个很久以前引入的错误，任何更改都会破坏大量的现有软件。
-spec subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> result() when ConnectionRef :: ssh:connection_ref(), ChannelId :: ssh:channel_id(), Subsystem :: string(), Timeout :: timeout().
由客户端通道进程调用，以请求在服务器上执行预定义的子系统。
函数 subsystem/4 和后续的 send/3,4,5 调用必须在同一个进程中执行。