檢視原始碼 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 code: 53, mnemonic name ECHO erlang atom: 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，呼叫此函式會變成「noop」。在處理包含 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 code: 53, mnemonic name ECHO erlang atom: 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，呼叫此函式會變成「noop」。在處理包含 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 為 infinity 原子，則等同於 send(ConnectionRef, ChannelId, 0, Data, infinity)。
如果呼叫時最後一個參數不是整數或 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 呼叫必須在同一個程序中執行。