ssh: ssh_channel replaced by ssh_client_channel

1 files changed, 0 insertions, 434 deletions

diff --git a/lib/ssh/doc/src/ssh_channel.xml b/lib/ssh/doc/src/ssh_channel.xml
deleted file mode 100644
index 63a480d747..0000000000
--- a/lib/ssh/doc/src/ssh_channel.xml
+++ /dev/null
@@ -1,434 +0,0 @@
-<?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_channel</title>
-    <prepared></prepared>
-    <docno></docno>
-    <date></date>
-    <rev></rev>
-  </header>
-  <module>ssh_channel</module>
-  <modulesummary>-behaviour(ssh_channel).
-  </modulesummary>
-  <description>
-    <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_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_channel</c>
-	process. Does not return, instead the calling process
-	enters the <c>ssh_channel</c> process receive loop and become an
-	<c>ssh_channel process</c>. 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_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_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_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>