diff options
Diffstat (limited to 'lib/ssh/doc/src/ssh_client_channel.xml')
| -rw-r--r-- | lib/ssh/doc/src/ssh_client_channel.xml | 440 |
1 files changed, 440 insertions, 0 deletions
diff --git a/lib/ssh/doc/src/ssh_client_channel.xml b/lib/ssh/doc/src/ssh_client_channel.xml new file mode 100644 index 0000000000..eed49beffa --- /dev/null +++ b/lib/ssh/doc/src/ssh_client_channel.xml @@ -0,0 +1,440 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2009</year> + <year>2016</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + <title>ssh_client_channel</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <module>ssh_client_channel</module> + <modulesummary>-behaviour(ssh_client_channel). (Replaces ssh_channel) + </modulesummary> + <description> + <note> + <p>This module replaces ssh_channel.</p> + <p>The old module is still available for compatibility, but should not be used for new programs. + The old module will not be maintained except for some error corrections + </p> + </note> + <p>SSH services (clients and servers) are implemented as channels + that are multiplexed over an SSH connection and communicates over + the <url href="http://www.ietf.org/rfc/rfc4254.txt"> SSH + Connection Protocol</url>. This module provides a callback API + that takes care of generic channel aspects for clients, such as flow control + and close messages. It lets the callback functions take care of + the service (application) specific parts. This behavior also ensures + that the channel process honors the principal of an OTP-process so + that it can be part of a supervisor tree. This is a requirement of + channel processes implementing a subsystem that will be added to + the <c>ssh</c> applications supervisor tree. + </p> + + <note><p>When implementing a <c>ssh</c> subsystem for daemons, use + <seealso marker="ssh_server_channel">-behaviour(ssh_server_channel)</seealso> (Replaces ssh_daemon_channel) + instead. + </p> + </note> + + <dont> + <p>Functions in this module are not supposed to be called outside a module implementing this + behaviour! + </p> + </dont> + + </description> + + <funcs> + <func> + <name>call(ChannelRef, Msg) -></name> + <name>call(ChannelRef, Msg, Timeout) -> Reply | {error, Reason}</name> + <fsummary>Makes a synchronous call to a channel.</fsummary> + <type> + <v>ChannelRef = pid() </v> + <d>As returned by <seealso marker = "#start_link-4">start_link/4</seealso></d> + <v>Msg = term()</v> + <v>Timeout = timeout()</v> + <v>Reply = term()</v> + <v>Reason = closed | timeout</v> + + </type> + <desc> + <p>Makes a synchronous call to the channel process by sending + a message and waiting until a reply arrives, or a time-out + occurs. The channel calls <seealso marker = + "#Module:handle_call-3">Module:handle_call/3</seealso> + to handle the message. If the channel process does not exist, + <c>{error, closed}</c> is returned. + </p> + </desc> + </func> + + <func> + <name>cast(ChannelRef, Msg) -> ok </name> + <fsummary>Sends an asynchronous message to the channel + ChannelRef and returns ok.</fsummary> + <type> + <v>ChannelRef = pid()</v> + <d>As returned by <seealso marker = "#start_link-4">start_link/4</seealso></d> + <v>Msg = term()</v> + </type> + <desc> + <p>Sends an asynchronous message to the channel process and + returns ok immediately, ignoring if the destination node or + channel process does not exist. The channel calls + <seealso marker = "#Module:handle_cast-2">Module:handle_cast/2</seealso> + to handle the message. + </p> + </desc> + </func> + + <func> + <name>enter_loop(State) -> _ </name> + <fsummary>Makes an existing process an ssh_client_channel (replaces ssh_channel) process.</fsummary> + <type> + <v>State = term()</v> + <d>as returned by <seealso marker = "#init-1">init/1</seealso></d> + </type> + <desc> + <p>Makes an existing process an <c>ssh_client_channel</c> (replaces ssh_channel) + process. Does not return, instead the calling process + enters the <c>ssh_client_channel</c> (replaces ssh_channel) process receive loop and become an + <c>ssh_client_channel</c> process. The process must have been started using + one of the start functions in <c>proc_lib</c>, see the <seealso + marker="stdlib:proc_lib">proc_lib(3)</seealso> manual page in STDLIB. + The user is responsible for any initialization of the process + and must call <seealso marker = "#init-1">init/1</seealso>. + </p> + </desc> + </func> + + <func> + <name>init(Options) -> {ok, State} | {ok, State, Timeout} | {stop, Reason} </name> + <fsummary>Initiates an <c>ssh_client_channel</c> process.</fsummary> + <type> + <v>Options = [{Option, Value}]</v> + <v>State = term()</v> + <v>Timeout = timeout()</v> + <v>Reason = term()</v> + </type> + <desc> + <p> + The following options must be present: + </p> + <taglist> + <tag><c>{channel_cb, atom()}</c></tag> + <item><p>The module that implements the channel behaviour.</p></item> + + <tag><c>{init_args(), list()}</c></tag> + <item><p>The list of arguments to the <c>init</c> function of the callback module.</p></item> + + <tag><c>{cm, ssh:connection_ref()}</c></tag> + <item><p>Reference to the <c>ssh</c> connection as returned by + <seealso marker="ssh#connect-3">ssh:connect/3</seealso>. + </p></item> + + <tag><c>{channel_id, ssh:channel_id()}</c></tag> + <item><p>Id of the <c>ssh</c> channel as returned by + <seealso marker="ssh_connection#session_channel/2">ssh_connection:session_channel/2,4</seealso>. + </p></item> + + </taglist> + + <note><p>This function is normally not called by the + user. The user only needs to call if the + channel process needs to be started with help of + <c>proc_lib</c> instead of calling + <c>start/4</c> or + <c>start_link/4</c>.</p> + </note> + </desc> + </func> + + <func> + <name>reply(Client, Reply) -> _</name> + <fsummary>Sends a reply to a client.</fsummary> + <type> + <v>Client = opaque()</v> + <v>Reply = term()</v> + </type> + <desc> + <p>This function can be used by a channel to send a + reply to a client that called <c>call/[2,3]</c> when the reply + cannot be defined in the return value of + <seealso marker ="#Module:handle_call-3">Module:handle_call/3</seealso>.</p> + <p><c>Client</c> must be the <c>From</c> argument provided to + the callback function <c>handle_call/3</c>. + <c>Reply</c> is an arbitrary term, + which is given back to the client as the return value of + <seealso marker="#call-2">call/[2,3].</seealso></p> + </desc> + </func> + + <func> + <name>start(SshConnection, ChannelId, ChannelCb, CbInitArgs) -> </name> + <name>start_link(SshConnection, ChannelId, ChannelCb, CbInitArgs) -> + {ok, ChannelRef} | {error, Reason}</name> + <fsummary>Starts a process that handles an SSH channel.</fsummary> + <type> + <v>SshConnection = ssh:connection_ref()</v> + <d>As returned by <seealso marker="ssh#connect-3">ssh:connect/3</seealso></d> + + <v>ChannelId = <seealso marker="ssh#type-channel_id">ssh:channel_id()</seealso></v> + <d>As returned by + <seealso marker ="ssh_connection#session_channel/2"> + ssh_connection:session_channel/[2,4]</seealso>.</d> + + <v>ChannelCb = atom()</v> + <d>Name of the module implementing the service-specific parts + of the channel.</d> + + <v>CbInitArgs = [term()]</v> + <d>Argument list for the <c>init</c> function in the callback module.</d> + + <v>ChannelRef = pid()</v> + </type> + <desc> + <p>Starts a process that handles an SSH channel. It is + called internally, by the <c>ssh</c> daemon, or explicitly by the <c>ssh</c> + client implementations. The behavior sets the + <c>trap_exit</c> flag to <c>true</c>. + </p> + </desc> + </func> + + </funcs> + + <section> + <title>Callback Functions</title> + <p> + The following functions are to be exported from a + <c>ssh_client_channel</c> callback module. + </p> + <marker id="cb_timeouts"></marker> + <section> + <title>Callback timeouts</title> + <p>The timeout values that can be returned by the callback functions + have the same semantics as in a <seealso marker="stdlib:gen_server">gen_server</seealso>. + If the time-out occurs, <seealso marker="#Module:handle_msg-2">handle_msg/2</seealso> + is called as <c>handle_msg(timeout, State)</c>.</p> + </section> + </section> + + <funcs> + <func> + <name>Module:code_change(OldVsn, State, Extra) -> {ok, + NewState}</name> + <fsummary>Converts process state when code is changed.</fsummary> + <type> + <v>OldVsn = term()</v> + <d>In the case of an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and + in the case of a downgrade, <c>OldVsn</c> is + <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the <c>vsn</c> + attribute(s) of the old version of the callback module + <c>Module</c>. If no such attribute is defined, the version is + the checksum of the BEAM file.</d> + <v>State = term()</v> + <d>Internal state of the channel.</d> + <v>Extra = term()</v> + <d>Passed "as-is" from the <c>{advanced,Extra}</c> + part of the update instruction.</d> + </type> + <desc> + <p>Converts process state when code is changed.</p> + + <p>This function is called by a client-side channel when it + is to update its internal state during a release + upgrade or downgrade, that is, when the instruction + <c>{update,Module,Change,...}</c>, where + <c>Change={advanced,Extra}</c>, is given in the <c>appup</c> + file. For more information, refer to Section 9.11.6 + Release Handling Instructions in the + <seealso marker="doc/design_principles:release_handling#instr">System Documentation</seealso>. + </p> + + <note><p>Soft upgrade according to the OTP release concept + is not straight forward for the server side, as subsystem + channel processes are spawned by the <c>ssh</c> application and + hence added to its supervisor tree. The subsystem channels can + be upgraded when upgrading the user application, if the callback + functions can handle two versions of the state, but this function + cannot be used in the normal way.</p> + </note> + + </desc> + </func> + + <func> + <name>Module:init(Args) -> {ok, State} | {ok, State, timeout()} | + {stop, Reason}</name> + <fsummary>Makes necessary initializations and returns the + initial channel state if the initializations succeed.</fsummary> + <type> + <v>Args = term()</v> + <d>Last argument to <c>start_link/4</c>.</d> + <v>State = term()</v> + <v>Reason = term()</v> + </type> + <desc> + <p>Makes necessary initializations and returns the initial channel + state if the initializations succeed. + </p> + <p>For more detailed information on time-outs, see Section + <seealso marker="#cb_timeouts">Callback timeouts</seealso>. </p> + </desc> + </func> + + <func> + <name>Module:handle_call(Msg, From, State) -> Result</name> + <fsummary>Handles messages sent by calling + <c>call/[2,3]</c>.</fsummary> + <type> + <v>Msg = term()</v> + <v>From = opaque()</v> + <d>Is to be used as argument to + <seealso marker="#reply-2">reply/2</seealso></d> + <v>State = term()</v> + <v>Result = {reply, Reply, NewState} | {reply, Reply, NewState, timeout()} + | {noreply, NewState} | {noreply , NewState, timeout()} + | {stop, Reason, Reply, NewState} | {stop, Reason, NewState} </v> + <v>Reply = term()</v> + <d>Will be the return value of <seealso marker="#call-2">call/[2,3]</seealso></d> + <v>NewState = term()</v> + <v>Reason = term()</v> + </type> + <desc> + <p>Handles messages sent by calling + <seealso marker="#call-2">call/[2,3]</seealso> + </p> + <p>For more detailed information on time-outs,, see Section + <seealso marker="#cb_timeouts">Callback timeouts</seealso>.</p> + </desc> + </func> + + <func> + <name>Module:handle_cast(Msg, State) -> Result</name> + <fsummary>Handles messages sent by calling + <c>cast/2</c>.</fsummary> + <type> + <v>Msg = term()</v> + <v>State = term()</v> + <v>Result = {noreply, NewState} | {noreply, NewState, timeout()} + | {stop, Reason, NewState}</v> + <v>NewState = term() </v> + <v>Reason = term()</v> + </type> + <desc> + <p>Handles messages sent by calling + <c>cast/2</c>. + </p> + <p>For more detailed information on time-outs, see Section + <seealso marker="#cb_timeouts">Callback timeouts</seealso>.</p> + </desc> + </func> + + <func> + <name>Module:handle_msg(Msg, State) -> {ok, State} | + {stop, ChannelId, State}</name> + + <fsummary>Handles other messages than SSH connection protocol, + call, or cast messages sent to the channel.</fsummary> + <type> + <v>Msg = timeout | term()</v> + <v>ChannelId = <seealso marker="ssh#type-channel_id">ssh:channel_id()</seealso></v> + <v>State = term() </v> + </type> + <desc> + <p>Handles other messages than SSH Connection Protocol, call, or + cast messages sent to the channel. + </p> + + <p>Possible Erlang 'EXIT' messages is to be handled by this + function and all channels are to handle the following message.</p> + + <taglist> + <tag><c>{ssh_channel_up, ssh:channel_id(), ssh:connection_ref()}</c></tag> + <item><p>This is the first message that the channel receives. + It is sent just before the <seealso + marker="#init-1">init/1</seealso> function + returns successfully. This is especially useful if the + server wants to send a message to the client without first + receiving a message from it. If the message is not + useful for your particular scenario, ignore it by + immediately returning <c>{ok, State}</c>. + </p></item> + </taglist> + </desc> + </func> + + <func> + <name>Module:handle_ssh_msg(Msg, State) -> {ok, State} | {stop, + ChannelId, State}</name> + <fsummary>Handles <c>ssh</c> connection protocol messages.</fsummary> + <type> + <v>Msg = ssh_connection:event()</v> + <v>ChannelId = <seealso marker="ssh#type-channel_id">ssh:channel_id()</seealso></v> + <v>State = term()</v> + </type> + <desc> + <p>Handles SSH Connection Protocol messages that may need + service-specific attention. For details, + see <seealso marker="ssh_connection"> ssh_connection:event()</seealso>. + </p> + + <p>The following message is taken care of by the + <c>ssh_client_channel</c> behavior.</p> + + <taglist> + <tag><c>{closed, ssh:channel_id()}</c></tag> + <item><p>The channel behavior sends a close message to the + other side, if such a message has not already been sent. + Then it terminates the channel with reason <c>normal</c>.</p></item> + </taglist> + </desc> + </func> + + <func> + <name>Module:terminate(Reason, State) -> _</name> + <fsummary>Does cleaning up before channel process termination. + </fsummary> + <type> + <v>Reason = term()</v> + <v>State = term()</v> + </type> + <desc> + <p>This function is called by a channel process when it is + about to terminate. Before this function is called, <seealso + marker="ssh_connection#close-2"> ssh_connection:close/2 + </seealso> is called, if it has not been called earlier. + This function does any necessary cleaning + up. When it returns, the channel process terminates with + reason <c>Reason</c>. The return value is ignored. + </p> + </desc> + </func> + + </funcs> + +</erlref> |