diff options
Diffstat (limited to 'lib/ssh/doc/src/ssh_channel.xml')
| -rw-r--r-- | lib/ssh/doc/src/ssh_channel.xml | 443 |
1 files changed, 0 insertions, 443 deletions
diff --git a/lib/ssh/doc/src/ssh_channel.xml b/lib/ssh/doc/src/ssh_channel.xml deleted file mode 100644 index 7b598494f7..0000000000 --- a/lib/ssh/doc/src/ssh_channel.xml +++ /dev/null @@ -1,443 +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, 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 an <c>ssh</c> subsystem, use - <c>-behaviour(ssh_daemon_channel)</c> instead of <c>-behaviour(ssh_channel)</c>. - The reason is that the only relevant callback functions for subsystems are - <c>init/1</c>, <c>handle_ssh_msg/2</c>, <c>handle_msg/2</c>, and <c>terminate/2</c>. - So, the <c>ssh_daemon_channel</c> behaviour is a limited version of the - <c>ssh_channel</c> behaviour. - </p></note> - </description> - - <section> - <title>DATA TYPES</title> - - <p>Type definitions that are used more than once in this module, - or abstractions to indicate the intended use of the data - type, or both:</p> - - <taglist> - <tag><c>boolean() =</c></tag> - <item><p><c>true | false</c></p></item> - <tag><c>string() =</c></tag> - <item><p>list of ASCII characters</p></item> - <tag><c>timeout() =</c></tag> - <item><p><c>infinity | integer()</c> in milliseconds</p></item> - <tag><c>ssh_connection_ref() =</c></tag> - <item><p>opaque() -as returned by - <c>ssh:connect/3</c> or sent to an SSH channel process</p></item> - <tag><c>ssh_channel_id() =</c></tag> - <item><p><c>integer()</c></p></item> - <tag><c>ssh_data_type_code() =</c></tag> - <item><p><c>1</c> ("stderr") | <c>0</c> ("normal") are - the valid values, - see <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url> - Section 5.2</p></item> - </taglist> - </section> - - <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">ssh_channel: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">ssh_channel: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">ssh_channel: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">ssh_channel: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><![CDATA[{channel_cb, atom()}]]></c></tag> - <item><p>The module that implements the channel behaviour.</p></item> - - <tag><c><![CDATA[{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><![CDATA[{cm, 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><![CDATA[{channel_id, channel_id()}]]></c></tag> - <item><p>Id of the <c>ssh</c> channel.</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>ssh_channel:start/4</c> or - <c>ssh_channel: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">ssh_channel: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> - <v>ChannelId = ssh_channel_id()</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> - <marker id="cb_timeouts"></marker> - <title>CALLBACK TIME-OUTS</title> - - <p>The time-out 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> - - <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>ssh_channel: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 TIME-OUTS</seealso>. </p> - </desc> - </func> - - <func> - <name>Module:handle_call(Msg, From, State) -> Result</name> - <fsummary>Handles messages sent by calling - <c>ssh_channel: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">ssh_channel: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">ssh_channel: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">ssh_channel:call/[2,3]</seealso> - </p> - <p>For more detailed information on time-outs,, see Section - <seealso marker="#cb_timeouts">CALLBACK TIME-OUTS</seealso>.</p> - </desc> - </func> - - <func> - <name>Module:handle_cast(Msg, State) -> Result</name> - <fsummary>Handles messages sent by calling - <c>ssh_channel:cact/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>ssh_channel:cast/2</c>. - </p> - <p>For more detailed information on time-outs, see Section - <seealso marker="#cb_timeouts">CALLBACK TIME-OUTS</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 = ssh_channel_id()</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><![CDATA[{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">ssh_channel: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 = ssh_channel_id()</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><![CDATA[{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> |