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
24       (application) specific parts. This behavior also ensures that the chan‐
25       nel process honors the principal of an OTP-process so that  it  can  be
26       part  of  a supervisor tree. This is a requirement of channel processes
27       implementing a subsystem that will be added  to  the  ssh  applications
28       supervisor 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
152              internally, by the ssh daemon, or explicitly by the  ssh  client
153              implementations. 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   Callback timeouts
160       The timeout values that can be returned by the callback functions  have
161       the  same  semantics  as  in a gen_server. If the time-out occurs, han‐
162       dle_msg/2 is called as handle_msg(timeout, State).
163

EXPORTS

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