1ssh_client_channel(3)      Erlang Module Definition      ssh_client_channel(3)
2
3
4

NAME

6       ssh_client_channel    -    -behaviour(ssh_client_channel).    (Replaces
7       ssh_channel)
8
9

DESCRIPTION

11   Note:
12       This module replaces ssh_channel.
13
14       The old module is still available for compatibility, but should not  be
15       used for new programs. The old module will not be maintained except for
16       some error corrections
17
18
19       SSH services (clients and servers) are implemented as channels that are
20       multiplexed  over an SSH connection and communicates over the  SSH Con‐
21       nection Protocol. This module provides a callback API that  takes  care
22       of  generic channel aspects for clients, such as flow control and close
23       messages. It lets the callback functions take care of the service  (ap‐
24       plication)  specific parts. This behavior also ensures that the channel
25       process honors the principal of an OTP-process so that it can  be  part
26       of a supervisor tree. This is a requirement of channel processes imple‐
27       menting a subsystem that will be added to the ssh applications supervi‐
28       sor tree.
29
30   Note:
31       When   implementing   a   ssh   subsystem   for  daemons,  use  -behav‐
32       iour(ssh_server_channel) (Replaces ssh_daemon_channel) instead.
33
34
35   Dont:
36       Functions in this module are not supposed to be called outside a module
37       implementing this behaviour!
38
39

EXPORTS

41       call(ChannelRef, Msg) ->
42       call(ChannelRef, Msg, Timeout) -> Reply | {error, Reason}
43
44              Types:
45
46                 ChannelRef = pid()
47                   As returned by start_link/4
48                 Msg = term()
49                 Timeout = timeout()
50                 Reply = term()
51                 Reason = closed | timeout
52
53              Makes  a  synchronous  call  to the channel process by sending a
54              message and waiting until a reply arrives, or a time-out occurs.
55              The channel calls Module:handle_call/3 to handle the message. If
56              the channel process does not exist, {error, closed} is returned.
57
58       cast(ChannelRef, Msg) -> ok
59
60              Types:
61
62                 ChannelRef = pid()
63                   As returned by start_link/4
64                 Msg = term()
65
66              Sends an asynchronous message to the channel process and returns
67              ok  immediately,  ignoring  if  the  destination node or channel
68              process does not exist. The channel  calls  Module:handle_cast/2
69              to handle the message.
70
71       enter_loop(State) -> _
72
73              Types:
74
75                 State = term()
76                   as returned by init/1
77
78              Makes   an  existing  process  an  ssh_client_channel  (replaces
79              ssh_channel) process.  Does  not  return,  instead  the  calling
80              process  enters  the  ssh_client_channel  (replaces ssh_channel)
81              process receive loop and become an  ssh_client_channel  process.
82              The  process must have been started using one of the start func‐
83              tions in proc_lib, see the proc_lib(3) manual  page  in  STDLIB.
84              The  user  is  responsible for any initialization of the process
85              and must call init/1.
86
87       init(Options) -> {ok, State} | {ok, State, Timeout} | {stop, Reason}
88
89              Types:
90
91                 Options = [{Option, Value}]
92                 State = term()
93                 Timeout = timeout()
94                 Reason = term()
95
96              The following options must be present:
97
98                {channel_cb, atom()}:
99                  The module that implements the channel behaviour.
100
101                {init_args(), list()}:
102                  The list of arguments to the init function of  the  callback
103                  module.
104
105                {cm, ssh:connection_ref()}:
106                  Reference  to  the  ssh  connection  as returned by ssh:con‐
107                  nect/3.
108
109                {channel_id, ssh:channel_id()}:
110                  Id of the ssh channel  as  returned  by  ssh_connection:ses‐
111                  sion_channel/2,4.
112
113          Note:
114              This  function is normally not called by the user. The user only
115              needs to call if the channel process needs to  be  started  with
116              help of proc_lib instead of calling start/4 or start_link/4.
117
118
119       reply(Client, Reply) -> _
120
121              Types:
122
123                 Client = opaque()
124                 Reply = term()
125
126              This  function  can  be  used  by a channel to send a reply to a
127              client that called call/[2,3] when the reply cannot  be  defined
128              in the return value of Module:handle_call/3.
129
130              Client  must be the From argument provided to the callback func‐
131              tion handle_call/3. Reply is an arbitrary term, which  is  given
132              back to the client as the return value of call/[2,3].
133
134       start(SshConnection, ChannelId, ChannelCb, CbInitArgs) ->
135       start_link(SshConnection,  ChannelId,  ChannelCb,  CbInitArgs)  -> {ok,
136       ChannelRef} | {error, Reason}
137
138              Types:
139
140                 SshConnection = ssh:connection_ref()
141                   As returned by ssh:connect/3
142                 ChannelId = ssh:channel_id()
143                   As returned by  ssh_connection:session_channel/[2,4].
144                 ChannelCb = atom()
145                   Name of the module implementing the service-specific  parts
146                   of the channel.
147                 CbInitArgs = [term()]
148                   Argument list for the init function in the callback module.
149                 ChannelRef = pid()
150
151              Starts  a  process that handles an SSH channel. It is called in‐
152              ternally, by the ssh daemon, or explicitly by the ssh client im‐
153              plementations. The behavior sets the trap_exit flag to true.
154

CALLBACK FUNCTIONS

156       The  following  functions  are to be exported from a ssh_client_channel
157       callback module.
158
159       The timeout values that can be returned by the callback functions  have
160       the  same  semantics  as  in a gen_server. If the time-out occurs, han‐
161       dle_msg/2 is called as handle_msg(timeout, State).
162

EXPORTS

164       Module:code_change(OldVsn, State, Extra) -> {ok, NewState}
165
166              Types:
167
168                 OldVsn = term()
169                   In the case of an upgrade, OldVsn is Vsn, and in  the  case
170                   of a downgrade, OldVsn is {down,Vsn}. Vsn is defined by the
171                   vsn attribute(s) of the old version of the callback  module
172                   Module. If no such attribute is defined, the version is the
173                   checksum of the BEAM file.
174                 State = term()
175                   Internal state of the channel.
176                 Extra = term()
177                   Passed "as-is" from the {advanced,Extra} part of the update
178                   instruction.
179
180              Converts process state when code is changed.
181
182              This  function  is called by a client-side channel when it is to
183              update its internal state during a release upgrade or downgrade,
184              that  is, when the instruction {update,Module,Change,...}, where
185              Change={advanced,Extra}, is given in the appup  file.  For  more
186              information,  refer  to Section 9.11.6 Release Handling Instruc‐
187              tions in the System Documentation.
188
189          Note:
190              Soft upgrade  according  to  the  OTP  release  concept  is  not
191              straight  forward for the server side, as subsystem channel pro‐
192              cesses are spawned by the ssh application and hence added to its
193              supervisor tree. The subsystem channels can be upgraded when up‐
194              grading the user application, if the callback functions can han‐
195              dle  two versions of the state, but this function cannot be used
196              in the normal way.
197
198
199       Module:init(Args) -> {ok, State} | {ok, State, timeout()} | {stop, Rea‐
200       son}
201
202              Types:
203
204                 Args = term()
205                   Last argument to start_link/4.
206                 State = term()
207                 Reason = term()
208
209              Makes  necessary initializations and returns the initial channel
210              state if the initializations succeed.
211
212              For more detailed information on time-outs, see Section Callback
213              timeouts.
214
215       Module:handle_call(Msg, From, State) -> Result
216
217              Types:
218
219                 Msg = term()
220                 From = opaque()
221                   Is to be used as argument to reply/2
222                 State = term()
223                 Result  = {reply, Reply, NewState} | {reply, Reply, NewState,
224                 timeout()} | {noreply, NewState} | {noreply , NewState, time‐
225                 out()}  |  {stop,  Reason,  Reply, NewState} | {stop, Reason,
226                 NewState}
227                 Reply = term()
228                   Will be the return value of call/[2,3]
229                 NewState = term()
230                 Reason = term()
231
232              Handles messages sent by calling call/[2,3]
233
234              For more detailed information on time-outs,, see  Section  Call‐
235              back timeouts.
236
237       Module:handle_cast(Msg, State) -> Result
238
239              Types:
240
241                 Msg = term()
242                 State = term()
243                 Result = {noreply, NewState} | {noreply, NewState, timeout()}
244                 | {stop, Reason, NewState}
245                 NewState = term()
246                 Reason = term()
247
248              Handles messages sent by calling cast/2.
249
250              For more detailed information on time-outs, see Section Callback
251              timeouts.
252
253       Module:handle_msg(Msg, State) -> {ok, State} | {stop, ChannelId, State}
254
255              Types:
256
257                 Msg = timeout | term()
258                 ChannelId = ssh:channel_id()
259                 State = term()
260
261              Handles  other  messages  than SSH Connection Protocol, call, or
262              cast messages sent to the channel.
263
264              Possible Erlang 'EXIT' messages is to be handled by  this  func‐
265              tion and all channels are to handle the following message.
266
267                {ssh_channel_up, ssh:channel_id(), ssh:connection_ref()}:
268                  This  is  the first message that the channel receives. It is
269                  sent just before the init/1 function  returns  successfully.
270                  This is especially useful if the server wants to send a mes‐
271                  sage to the client without first receiving  a  message  from
272                  it.  If  the  message is not useful for your particular sce‐
273                  nario, ignore it by immediately returning {ok, State}.
274
275       Module:handle_ssh_msg(Msg, State) -> {ok, State}  |  {stop,  ChannelId,
276       State}
277
278              Types:
279
280                 Msg = ssh_connection:event()
281                 ChannelId = ssh:channel_id()
282                 State = term()
283
284              Handles  SSH Connection Protocol messages that may need service-
285              specific attention. For details, see ssh_connection:event().
286
287              The following message is taken care of by the ssh_client_channel
288              behavior.
289
290                {closed, ssh:channel_id()}:
291                  The  channel  behavior  sends  a  close message to the other
292                  side, if such a message has not already been sent.  Then  it
293                  terminates the channel with reason normal.
294
295       Module:terminate(Reason, State) -> _
296
297              Types:
298
299                 Reason = term()
300                 State = term()
301
302              This function is called by a channel process when it is about to
303              terminate.  Before  this  function   is   called,    ssh_connec‐
304              tion:close/2  is called, if it has not been called earlier. This
305              function does any necessary cleaning up. When  it  returns,  the
306              channel  process terminates with reason Reason. The return value
307              is ignored.
308
309
310
311Ericsson AB                       ssh 4.12.5             ssh_client_channel(3)
Impressum