Included Modules
Constants
VALID_PTY_OPTIONS = { :term=>"xterm", :chars_wide=>80, :chars_high=>24, :pixels_wide=>640, :pixels_high=>480, :modes=>{}, :want_reply=>false }
Attributes
[R] connection The connection driver instance that owns this channel
[R] local_id The channel’s local id (assigned by the connection)
[R] local_maximum_packet_size The maximum packet size that may be sent over this channel
[R] local_window_size The maximum data window size for this channel
[R] maximum_packet_size The maximum packet size that may be sent over this channel
[R] remote_id The channel’s remote id (assigned by the remote server)
[R] type The type of this channel
[R] window_size The maximum data window size for this channel
Public Class methods
create( connection, log, buffers, type, remote_id, window_size, packet_size )

Creates a new channel object with the given internal information. The channel is assumed to already be connected to a remote host.

    # File lib/net/ssh/connection/channel.rb, line 87
87:         def self.create( connection, log, buffers, type, remote_id,
88:           window_size, packet_size )
89:         # begin
90:           channel = new( connection, log, buffers, type )
91:           channel.do_confirm_open remote_id, window_size, packet_size
92:           channel
93:         end
event( event, *parameters )

A convenience method for defining new event callbacks.

     # File lib/net/ssh/connection/channel.rb, line 414
414:         def self.event( event, *parameters )
415:           define_method "do_#{event}" do |*args|
416:             callback event, self, *args
417:             self
418:           end
419:         end
new( connection, log, buffers, type )

Create a new channel object on the given connection, and of the given type.

     # File lib/net/ssh/connection/channel.rb, line 105
105:         def initialize( connection, log, buffers, type )
106:           @connection = connection
107:           @log = log
108:           @buffers = buffers
109:           @type = type
110:           @local_id = @connection.allocate_channel_id
111:           @local_window_size = 0x20000
112:           @local_maximum_packet_size = 0x10000
113:         end
open( connection, log, buffers, type, data=nil )

Requests that a new channel be opened on the remote host. This will return immediately, but the on_confirm_open callback will be invoked when the remote host confirms that the channel has been successfully opened.

    # File lib/net/ssh/connection/channel.rb, line 67
67:         def self.open( connection, log, buffers, type, data=nil )
68:           channel = new( connection, log, buffers, type )
69: 
70:           msg = buffers.writer
71: 
72:           msg.write_byte CHANNEL_OPEN
73:           msg.write_string type
74:           msg.write_long channel.local_id
75:           msg.write_long channel.local_window_size
76:           msg.write_long channel.local_maximum_packet_size
77:           msg.write data.to_s if data
78: 
79:           connection.send_message msg
80: 
81:           channel
82:         end
Public Instance methods
[]( name )

Alias for property

[]=( name, value )

Alias for set_property

close( client_initiated=true )

Closes the channel.

     # File lib/net/ssh/connection/channel.rb, line 210
210:         def close( client_initiated=true )
211:           unless defined?(@already_closed) && @already_closed
212:             msg = @buffers.writer
213:             msg.write_byte CHANNEL_CLOSE
214:             msg.write_long @remote_id
215:             @connection.send_message msg
216:             @already_closed = true
217:           end
218: 
219:           unless client_initiated
220:             @connection.remove_channel( self )
221:             callback :close, self
222:           end
223: 
224:           self
225:         end
do_confirm_failed( reason_code, description, language )

Invoked when the server failed to confirm the opening of a channel.

     # File lib/net/ssh/connection/channel.rb, line 430
430:         def do_confirm_failed( reason_code, description, language )
431:           @local_id = nil
432:           @connection = nil
433:           callback :confirm_failed, self, reason_code, description, language
434:         end
do_confirm_open( remote_id, window_size, packet_size )

Invoked when the server confirms the opening of a channel.

     # File lib/net/ssh/connection/channel.rb, line 422
422:         def do_confirm_open( remote_id, window_size, packet_size )
423:           @remote_id = remote_id
424:           @window_size = window_size
425:           @maximum_packet_size = packet_size
426:           callback :confirm_open, self
427:         end
do_data( data )

Invoked when the server sends a data packet. This in turn calls the "on_data" callback.

     # File lib/net/ssh/connection/channel.rb, line 445
445:         def do_data( data )
446:           update_local_window_size data
447:           callback :data, self, data
448:         end
do_extended_data( type, data )

Invoked when the server sends an extended data packet. This in turn calls the "on_extended_data" callback.

     # File lib/net/ssh/connection/channel.rb, line 452
452:         def do_extended_data( type, data )
453:           update_local_window_size data
454:           callback :extended_data, self, type, data
455:         end
do_window_adjust( bytes_to_add )

Invoked when the server asks to adjust the window size. This in turn calls the "on_window_adjust" callback.

     # File lib/net/ssh/connection/channel.rb, line 438
438:         def do_window_adjust( bytes_to_add )
439:           @window_size += bytes_to_add
440:           callback :window_adjust, self, bytes_to_add
441:         end
exec( command, want_reply=false )

Execute the given remote command over the channel. This should be invoked in the "on_confirm" callback of a channel. This method will return immediately.

     # File lib/net/ssh/connection/channel.rb, line 398
398:         def exec( command, want_reply=false )
399:           send_request_string "exec", command, want_reply
400:         end
on_close( &block )

Set the callback to be invoked when the channel is closed.

     # File lib/net/ssh/connection/channel.rb, line 176
176:         def on_close( &block )
177:           @on_close = block
178:         end
on_confirm_failed( &block )

Set the callback to use when the channel could not be opened for some reason.

     # File lib/net/ssh/connection/channel.rb, line 129
129:         def on_confirm_failed( &block )
130:           @on_confirm_failed = block
131:         end
on_confirm_open( &block )

Set the callback to use when the channel has been confirmed to be open.

     # File lib/net/ssh/connection/channel.rb, line 123
123:         def on_confirm_open( &block )
124:           @on_confirm_open = block
125:         end
on_data( &block )

Set the callback to be invoked when the server sends a data packet over the channel.

     # File lib/net/ssh/connection/channel.rb, line 141
141:         def on_data( &block )
142:           @on_data = block
143:         end
on_eof( &block )

Set the callback to be invoked when the server sends an EOF packet.

     # File lib/net/ssh/connection/channel.rb, line 153
153:         def on_eof( &block )
154:           @on_eof = block
155:         end
on_extended_data( &block )

Set the callback to be invoked when the server sends an extended data packet over the channel.

     # File lib/net/ssh/connection/channel.rb, line 147
147:         def on_extended_data( &block )
148:           @on_extended_data = block
149:         end
on_failure( &block )

Set the callback to invoked when the server sends notification of a failed operation.

     # File lib/net/ssh/connection/channel.rb, line 171
171:         def on_failure( &block )
172:           @on_failure = block
173:         end
on_request( &block )

Set the callback to be invoked when the server sends a request packet.

     # File lib/net/ssh/connection/channel.rb, line 159
159:         def on_request( &block )
160:           @on_request = block
161:         end
on_success( &block )

Set the callback to invoked when the server sends confirmation of a successful operation.

     # File lib/net/ssh/connection/channel.rb, line 165
165:         def on_success( &block )
166:           @on_success = block
167:         end
on_window_adjust( &block )

Set the callback to be invoked when the server requests that the window size be adjusted.

     # File lib/net/ssh/connection/channel.rb, line 135
135:         def on_window_adjust( &block )
136:           @on_window_adjust = block
137:         end
property( name )

Retrieved a named property of the channel.

This method is also aliased as []
     # File lib/net/ssh/connection/channel.rb, line 191
191:         def property( name )
192:           ( @properties ||= Hash.new )[ name ]
193:         end
request_pty( opts = {} )

Request that a pty be opened for this channel. Valid options are :term, :chars_wide, :chars_high, :pixels_wide, :pixels_high, :modes, and :want_reply. :modes is a Hash, where the keys are constants from Net::SSH::Service::Term, and values are integers describing the corresponding key.

     # File lib/net/ssh/connection/channel.rb, line 367
367:         def request_pty( opts = {} )
368:           invalid_opts = opts.keys - VALID_PTY_OPTIONS.keys
369:           unless invalid_opts.empty?
370:             raise ArgumentError,
371:               "invalid option(s) to request_pty: #{invalid_opts.inspect}"
372:           end
373: 
374:           opts = VALID_PTY_OPTIONS.merge( opts )
375: 
376:           msg = @buffers.writer
377:           msg.write_string opts[ :term ]
378:           msg.write_long opts[ :chars_wide ]
379:           msg.write_long opts[ :chars_high ]
380:           msg.write_long opts[ :pixels_wide ]
381:           msg.write_long opts[ :pixels_high ]
382: 
383:           modes = @buffers.writer
384:           opts[ :modes ].each do |mode, data|
385:             modes.write_byte mode
386:             modes.write_long data
387:           end
388:           modes.write_byte Term::TTY_OP_END
389: 
390:           msg.write_string modes.to_s
391: 
392:           send_request "pty-req", msg, opts[:want_reply]
393:         end
send_data( data )

Send a data packet to the server, over the channel.

     # File lib/net/ssh/connection/channel.rb, line 279
279:         def send_data( data )
280:           @connection.register_data_request( self, data )
281:         end
send_data_packet( data )

Send a data packet to the server, over the channel. Only sends as much of that data as the channel is currently capable of sending (based on window size and maximum packet size), and returns any data that could not be sent. Returns nil if all the data that was requested to be sent, was sent.

     # File lib/net/ssh/connection/channel.rb, line 321
321:         def send_data_packet( data )
322:           # overhead is ( byte.length + id.length + strlen.length ) = 9
323:           data, data_to_return = split_data_for_packet( data.to_s, 9 )
324:           @window_size -= data.length
325: 
326:           msg = @buffers.writer
327:           msg.write_byte CHANNEL_DATA
328:           msg.write_long @remote_id
329:           msg.write_string data
330:           @connection.send_message msg
331: 
332:           data_to_return
333:         end
send_eof()

Send an EOF across the channel. No data should be sent from the client to the server over this channel after this, although packets may still be received from the server.

     # File lib/net/ssh/connection/channel.rb, line 230
230:         def send_eof
231:           msg = @buffers.writer
232:           msg.write_byte CHANNEL_EOF
233:           msg.write_long @remote_id
234:           @connection.send_message msg
235:           self
236:         end
send_extended_data( type, data )

Send an extended data packet to the server, over the channel. Extended data always has a numeric type associated with it. The only predefined type is 1, whic corresponds to stderr data.

     # File lib/net/ssh/connection/channel.rb, line 286
286:         def send_extended_data( type, data )
287:           @connection.register_data_request( self, data, type )
288:         end
send_extended_data_packet( type, data )

Send an extended data packet to the server, over the channel. Extended data always has a numeric type associated with it. The only predefined type is 1, whic corresponds to stderr data.

     # File lib/net/ssh/connection/channel.rb, line 338
338:         def send_extended_data_packet( type, data )
339:           # overhead is
340:           #   ( byte.length + id.length + type.length + strlen.length ) = 13
341:           data, data_to_return = split_data_for_packet( data.to_s, 13 )
342:           @window_size -= data.length
343: 
344:           msg = @buffers.writer
345:           msg.write_byte CHANNEL_EXTENDED_DATA
346:           msg.write_long @remote_id
347:           msg.write_long type
348:           msg.write_string data
349:           @connection.send_message msg
350: 
351:           data_to_return
352:         end
send_request( request_name, data, want_reply=false )

Send a generic channel request with the given name. The data item will be written directly into the request (after converting it to a string, as necessary).

     # File lib/net/ssh/connection/channel.rb, line 256
256:         def send_request( request_name, data, want_reply=false )
257:           msg = @buffers.writer
258:           msg.write_byte CHANNEL_REQUEST
259:           msg.write_long @remote_id
260:           msg.write_string request_name
261:           msg.write_bool want_reply
262:           msg.write data.to_s
263:           @connection.send_message msg
264:           self
265:         end
send_request_string( request_name, data, want_reply=false )

Send a channel request with the given name. It will have one data item, which will be interpreted as a string.

     # File lib/net/ssh/connection/channel.rb, line 247
247:         def send_request_string( request_name, data, want_reply=false )
248:           msg = @buffers.writer
249:           msg.write_string data.to_s
250:           send_request request_name, msg, want_reply
251:         end
send_signal( sig, want_reply=false )

Send the given signal to process on the other side of the channel. The parameter should be one of the Channel::SIGxxx constants.

     # File lib/net/ssh/connection/channel.rb, line 240
240:         def send_signal( sig, want_reply=false )
241:           send_request_string "signal", sig, want_reply
242:           self
243:         end
send_window_adjust( size )

Send a "window adjust" message to the server for this channel, informing it that it may send this many more bytes over the channel.

     # File lib/net/ssh/connection/channel.rb, line 270
270:         def send_window_adjust( size )
271:           msg = @buffers.writer
272:           msg.write_byte CHANNEL_WINDOW_ADJUST
273:           msg.write_long @remote_id
274:           msg.write_long size
275:           @connection.send_message msg
276:         end
set_property( name, value )

Set a named property on the channel.

This method is also aliased as []=
     # File lib/net/ssh/connection/channel.rb, line 196
196:         def set_property( name, value )
197:           ( @properties ||= Hash.new )[ name ] = value
198:         end
subsystem( subsystem, want_reply=true )

Request the given subsystem. This method will return immediately.

     # File lib/net/ssh/connection/channel.rb, line 403
403:         def subsystem( subsystem, want_reply=true )
404:           send_request_string "subsystem", subsystem, want_reply
405:         end
valid?()
     # File lib/net/ssh/connection/channel.rb, line 186
186:         def valid?
187:           not @local_id.nil?
188:         end

[Validate]