From edbbc40fc3e4d5698408e109ac6f9fd301aae05f Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Mon, 5 Aug 2019 12:41:17 +0200 Subject: ssh: Update ssh_sftp:start_channel documentation and code The Typing in the old documentation was not up-to-date. The option handling and definition is slightly re-worked in the code also. Some comments added and a function moved inside the module. --- lib/ssh/doc/src/ssh_sftp.xml | 32 ++++++++++++++--------- lib/ssh/src/ssh.erl | 2 ++ lib/ssh/src/ssh_sftp.erl | 62 +++++++++++++++++++++++++++++++++++--------- 3 files changed, 72 insertions(+), 24 deletions(-) diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml index 76d2b21946..f9f1e0953b 100644 --- a/lib/ssh/doc/src/ssh_sftp.xml +++ b/lib/ssh/doc/src/ssh_sftp.xml @@ -38,6 +38,12 @@ + + + + + + Error cause @@ -423,25 +429,27 @@ start_channel(ConnectionRef) -> - start_channel(ConnectionRef, Options) -> - {ok, Pid} | {error, reason()|term()} + start_channel(ConnectionRef, SftpOptions) -> + {ok, ChannelPid} | Error + start_channel(Host) -> start_channel(Host, Options) -> - start_channel(Host, Port, Options) -> - {ok, Pid, ConnectionRef} | {error, reason()|term()} - + start_channel(Host, Port, Options) -> start_channel(TcpSocket) -> start_channel(TcpSocket, Options) -> - {ok, Pid, ConnectionRef} | {error, reason()|term()} + {ok, ChannelPid, ConnectionRef} | Error Starts an SFTP client. - Host = string() - ConnectionRef = connection_ref() - Port = integer() - TcpSocket = port() - The socket is supposed to be from gen_tcp:connect or gen_tcp:accept with option {active,false} - Options = [{Option, Value}] + Host = ssh:host() + Port = inet:port_number() + TcpSocket = ssh:open_socket() + Options = [ sftp_option() + | ssh:client_option() ] + SftpOptions = [ sftp_option() ] + ChannelPid = pid() + ConnectionRef = ssh:connection_ref() + Error = {error, reason()}

If no connection reference is provided, a connection is set diff --git a/lib/ssh/src/ssh.erl b/lib/ssh/src/ssh.erl index ff5aee14d7..32f10c797d 100644 --- a/lib/ssh/src/ssh.erl +++ b/lib/ssh/src/ssh.erl @@ -66,6 +66,8 @@ cipher_alg/0, mac_alg/0, compression_alg/0, + host/0, + open_socket/0, ip_port/0 ]). diff --git a/lib/ssh/src/ssh_sftp.erl b/lib/ssh/src/ssh_sftp.erl index 9162de3487..4b6e187c3a 100644 --- a/lib/ssh/src/ssh_sftp.erl +++ b/lib/ssh/src/ssh_sftp.erl @@ -92,34 +92,63 @@ -define(XF(S), S#state.xf). -define(REQID(S), S#state.req_id). +-type sftp_option() :: {timeout, timeout()} + | {sftp_vsn, pos_integer()} + | {window_size, pos_integer()} + | {packet_size, pos_integer()} . -type reason() :: atom() | string() | tuple() . %%==================================================================== %% API %%==================================================================== + + +%%%================================================================ +%%% + +%%%---------------------------------------------------------------- +%%% start_channel/1 + start_channel(Cm) when is_pid(Cm) -> start_channel(Cm, []); - + start_channel(Socket) when is_port(Socket) -> start_channel(Socket, []); -start_channel(Host) when is_list(Host) -> +start_channel(Host) -> start_channel(Host, []). --spec start_channel(ssh:connection_ref() | gen_tcp:socket() | string(), - ssh:client_options() - ) -> {ok,pid()} | {ok,pid(),ssh:connection_ref()} | {error,term()}. +%%%---------------------------------------------------------------- +%%% start_channel/2 + +%%% -spec:s are as if Dialyzer handled signatures for separate +%%% function clauses. + +-spec start_channel(ssh:open_socket(), + [ssh:client_options() | sftp_option()] + ) + -> {ok,pid(),ssh:connection_ref()} | {error,reason()}; + + (ssh:connection_ref(), + [sftp_option()] + ) + -> {ok,pid()} | {ok,pid(),ssh:connection_ref()} | {error,reason()}; + + (ssh:host(), + [ssh:client_options() | sftp_option()] + ) + -> {ok,pid(),ssh:connection_ref()} | {error,reason()} . start_channel(Socket, UserOptions) when is_port(Socket) -> - {SshOpts, _ChanOpts, SftpOpts} = handle_options(UserOptions), + {SshOpts, ChanOpts, SftpOpts} = handle_options(UserOptions), Timeout = % A mixture of ssh:connect and ssh_sftp:start_channel: proplists:get_value(connect_timeout, SshOpts, proplists:get_value(timeout, SftpOpts, infinity)), case ssh:connect(Socket, SshOpts, Timeout) of {ok,Cm} -> - case start_channel(Cm, UserOptions) of + case start_channel(Cm, ChanOpts ++ SftpOpts) of {ok, Pid} -> {ok, Pid, Cm}; Error -> @@ -155,8 +184,14 @@ start_channel(Host, UserOptions) -> start_channel(Host, 22, UserOptions). --spec start_channel(string(), integer(), ssh:client_options()) -> - {ok,pid(),ssh:connection_ref()} | {error,term()}. +%%%---------------------------------------------------------------- +%%% start_channel/3 + +-spec start_channel(ssh:host(), + inet:port_number(), + [ssh:client_option() | sftp_option()] + ) + -> {ok,pid(),ssh:connection_ref()} | {error,reason()}. start_channel(Host, Port, UserOptions) -> {SshOpts, ChanOpts, SftpOpts} = handle_options(UserOptions), @@ -182,7 +217,12 @@ start_channel(Host, Port, UserOptions) -> Error end. +%%% Helper for start_channel +wait_for_version_negotiation(Pid, Timeout) -> + call(Pid, wait_for_version_negotiation, Timeout). + +%%%---------------------------------------------------------------- -spec stop_channel(ChannelPid) -> ok when ChannelPid :: pid(). @@ -203,9 +243,7 @@ stop_channel(Pid) -> ok end. -wait_for_version_negotiation(Pid, Timeout) -> - call(Pid, wait_for_version_negotiation, Timeout). - +%%%---------------------------------------------------------------- -spec open(ChannelPid, Name, Mode) -> {ok, Handle} | Error when ChannelPid :: pid(), Name :: string(), -- cgit v1.2.3