Class | Net::SSH::Multi::Channel |
In: |
lib/net/ssh/multi/channel.rb
|
Parent: | Object |
Net::SSH::Multi::Channel encapsulates a collection of Net::SSH::Connection::Channel instances from multiple different connections. It allows for operations to be performed on all contained channels, simultaneously, using an interface mostly identical to Net::SSH::Connection::Channel itself.
You typically obtain a Net::SSH::Multi::Channel instance via Net::SSH::Multi::Session#open_channel or Net::SSH::Multi::Session#exec, though there is nothing stopping you from instantiating one yourself with a handful of Net::SSH::Connection::Channel objects (though they should be associated with connections managed by a Net::SSH::Multi::Session object for consistent behavior).
channel = session.open_channel do |ch| # ... end channel.wait
channels | [R] | The collection of Net::SSH::Connection::Channel instances that this multi-channel aggregates. |
connection | [R] | The Net::SSH::Multi::Session instance that controls this channel collection. |
properties | [R] | A Hash of custom properties that may be set and queried on this object. |
Instantiate a new Net::SSH::Multi::Channel instance, controlled by the given connection (a Net::SSH::Multi::Session object) and wrapping the given channels (Net::SSH::Connection::Channel instances).
You will typically never call this directly; rather, you‘ll get your multi-channel references via Net::SSH::Multi::Session#open_channel and friends.
# File lib/net/ssh/multi/channel.rb, line 38 38: def initialize(connection, channels) 39: @connection = connection 40: @channels = channels 41: @properties = {} 42: end
Retrieve the property (see properties) with the given key.
host = channel[:host]
# File lib/net/ssh/multi/channel.rb, line 53 53: def [](key) 54: @properties[key] 55: end
Set the property (see properties) with the given key to the given value.
channel[:visited] = true
# File lib/net/ssh/multi/channel.rb, line 61 61: def []=(key, value) 62: @properties[key] = value 63: end
Returns true as long as any of the component channels are active.
connection.loop { channel.active? }
# File lib/net/ssh/multi/channel.rb, line 112 112: def active? 113: channels.any? { |channel| channel.active? } 114: end
Closes all component channels.
# File lib/net/ssh/multi/channel.rb, line 127 127: def close 128: channels.each { |channel| channel.close } 129: self 130: end
Perform an exec command on all component channels. The block, if given, is passed to each component channel, so it will (potentially) be invoked once for every channel in the collection. The block will receive two parameters: the specific channel object being operated on, and a boolean indicating whether the exec succeeded or not.
channel.exec "ls -l" do |ch, success| # ... end
See the documentation in Net::SSH for Net::SSH::Connection::Channel#exec for more information on how to work with the callback.
# File lib/net/ssh/multi/channel.rb, line 77 77: def exec(command, &block) 78: channels.each { |channel| channel.exec(command, &block) } 79: self 80: end
Registers a callback on all component channels, to be invoked when the remote server terminates the channel. The callback will be invoked with one argument: the specific channel object being closed.
channel.on_close do |ch| # ... end
# File lib/net/ssh/multi/channel.rb, line 185 185: def on_close(&block) 186: channels.each { |channel| channel.on_close(&block) } 187: self 188: end
Registers a callback on all component channels, to be invoked when the remote process emits data (usually on its stdout stream). The block will be invoked with two arguments: the specific channel object, and the data that was received.
channel.on_data do |ch, data| puts "got data: #{data}" end
# File lib/net/ssh/multi/channel.rb, line 147 147: def on_data(&block) 148: channels.each { |channel| channel.on_data(&block) } 149: self 150: end
Registers a callback on all component channels, to be invoked when the remote server has no further data to send. The callback will be invoked with one argument: the specific channel object being marked EOF.
channel.on_eof do |ch| # ... end
# File lib/net/ssh/multi/channel.rb, line 197 197: def on_eof(&block) 198: channels.each { |channel| channel.on_eof(&block) } 199: self 200: end
Registers a callback on all component channels, to be invoked when the remote process emits "extended" data (typically on its stderr stream). The block will be invoked with three arguments: the specific channel object, an integer describing the data type (usually a 1 for stderr) and the data that was received.
channel.on_extended_data do |ch, type, data| puts "got extended data: #{data}" end
# File lib/net/ssh/multi/channel.rb, line 161 161: def on_extended_data(&block) 162: channels.each { |channel| channel.on_extended_data(&block) } 163: self 164: end
Registers a callback on all component channels, to be invoked when the remote server is unable to open the channel. The callback will be invoked with three arguments: the channel object that couldn‘t be opened, a description of the error (as a string), and an integer code representing the error.
channel.on_open_failed do |ch, description, code| # ... end
# File lib/net/ssh/multi/channel.rb, line 211 211: def on_open_failed(&block) 212: channels.each { |channel| channel.on_open_failed(&block) } 213: self 214: end
Registers a callback on all component channels, to be invoked during the idle portion of the connection event loop. The callback will be invoked with one argument: the specific channel object being processed.
channel.on_process do |ch| # ... end
# File lib/net/ssh/multi/channel.rb, line 173 173: def on_process(&block) 174: channels.each { |channel| channel.on_process(&block) } 175: self 176: end
Registers a callback on all component channels, to be invoked when the remote server sends a channel request of the given type. The callback will be invoked with two arguments: the specific channel object receiving the request, and a Net::SSH::Buffer instance containing the request-specific data.
channel.on_request("exit-status") do |ch, data| puts "exited with #{data.read_long}" end
# File lib/net/ssh/multi/channel.rb, line 225 225: def on_request(type, &block) 226: channels.each { |channel| channel.on_request(type, &block) } 227: self 228: end
Perform a request_pty command on all component channels. The block, if given, is passed to each component channel, so it will (potentially) be invoked once for every channel in the collection. The block will receive two parameters: the specific channel object being operated on, and a boolean indicating whether the pty request succeeded or not.
channel.request_pty do |ch, success| # ... end
See the documentation in Net::SSH for Net::SSH::Connection::Channel#request_pty for more information on how to work with the callback.
# File lib/net/ssh/multi/channel.rb, line 95 95: def request_pty(opts={}, &block) 96: channels.each { |channel| channel.request_pty(opts, &block) } 97: self 98: end
Send the given data to each component channel. It will be sent to the remote process, typically being received on the process’ stdin stream.
channel.send_data "password\n"
# File lib/net/ssh/multi/channel.rb, line 104 104: def send_data(data) 105: channels.each { |channel| channel.send_data(data) } 106: self 107: end