mtik 3.0.2

data/CHANGELOG.txt

@@ -0,0 +1,29 @@
+2010-02-05 (05 FEB 2010)  VERSION 3.0.2  Aaron D. Gifford (http://www.aarongifford.com)
+  * Typo fixes to example tikfetch.rb
+  * Multi-command functionality added to interactive client and to tikcommand.rb example
+  * Removed kludge path stuff for author's broken FreeBSD Ruby 1.9.1 gem system
+  * Removed lame JSON-ifier from example and switched to require 'json' instead
+
+2010-01-19 (19 JAN 2010)  VERSION 3.0.1  Aaron D. Gifford (http://www.aarongifford.com/)
+  * Added support for '/tool/fetch' 'requesting' state
+  * Added auto-cancel of finished '/tool/fetch' command in MTik#command()
+  * Added MTik::Request#cancel() method
+  * Added MTik::Request#state() attr_reader (and new @state object property to replace
+    the @completed boolean property)
+  * MTik::Request objects now associate with the appropriate MTik::Connection object
+    upon MTik::Connection transmitting the request to a device (which facilities)
+    the MTik::Request@cancel() method
+  * Removed gem root directory mtik.rb file that was acting as a kludge for the author's
+    messed-up FreeBSD Ruby 1.9 installation
+  * Renamed examples with a 'tik' prefix
+
+2010-01-15 (15 JAN 2010)  VERSION 3.0.0  Aaron D. Gifford  (http://www.aarongifford.com/)
+  * Bumped the version to 3.0.0 due to modularization and gemification changes
+  that break any software using the older Ruby API classes.
+  * Split out (as separate files) and added a few more examples:
+      cli.rb
+      command.rb
+      json.rb
+      fetch.rb
+  * Added VERSION.txt, CHANGELOG.txt, README.txt, LICENSE.txt, and *.gemspec files, moved
+    the example files into the bin subdirectory

data/LICENSE.txt

@@ -0,0 +1,36 @@
+########################################################################
+#--
+#
+# GEM:      MTik -- A Ruby gem implementing the MikroTik RouterOS API
+#
+#++
+# Author::    Aaron D. Gifford - http://www.aarongifford.com/
+# Copyright:: Copyright (c) 2009-2010, InfoWest, Inc.
+# License::   BSD license
+#--
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, the above list of authors and contributors, this list of
+#    conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. Neither the name of the author(s) or copyright holder(s) nor the
+#    names of any contributors may be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S), AUTHOR(S) AND
+# CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+# AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
+# IN NO EVENT SHALL THE COPYRIGHT HOLDER(S), AUTHOR(S), OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# DCONSEQUENTIAL AMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+# THE POSSIBILITY OF SUCH DAMAGE.
+########################################################################

data/README.txt

@@ -0,0 +1,64 @@
+= MTik -- A Ruby implementation of the MikroTik RouterOS API
+
+The MTik gem implements the MikroTik RouterOS API for connecting to
+devices running RouterOS (with the API enabled) over the network.
+
+
+== Examples
+
+Included in the examples subdirectory are four example ruby scripts
+that use the Ruby API implementation:
+
+tikcli.rb::     A command-line-like API interface
+tikcommand.rb:: A tool for executing a single API command from
+                a unix command-line
+tikfetch.rb::   A tool for instructing devices to download files
+                from specified URLs (unix command-line tool)
+tikjson.rb::    Like 'command.rb' a tool for executing a single
+                API command, except the output is formatted  in
+                JSON-style
+
+
+== Download
+
+The latest version of MTik can be found at
+
+* http://www.aarongifford.com/computers/mtik/
+
+Ruby RDoc documentation can be found online at
+
+* http://www.aarongifford.com/computers/mtik/latest/doc/ 
+
+Additional documentation is available at
+
+* http://www.aarongifford.com/computers/mtik/
+* http://wiki.mikrotik.com/wiki/API_Ruby_class
+
+For documentation on the MikroTik RouterOS APi, see
+
+* http://wiki.mikrotik.com/wiki/API
+
+
+== Installation
+
+To install MTik is through its GEM file:
+
+  % [sudo] gem install mtik-3.3.0.gem
+
+== License
+
+This gem and all other scripts and documentation files are licensed
+under a BSD-style license.  (See the LICENSE.txt file.)
+
+
+== Report Bugs
+
+Please report bugs by going to the author's web site and clicking on the
+"Contact Me" link in the left-hand menu.  The direct URL is:
+
+* http://www.aarongifford.com/leaveanote.html
+
+Thank you!
+
+-- Aaron D. Gifford
+

data/VERSION.txt

@@ -0,0 +1 @@
+3.0.2

data/examples/tikcli.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+########################################################################
+#--
+#
+# FILE:     tikcli.rb -- Example of using the Ruby MikroTik API in Ruby
+#
+#++
+# Author::    Aaron D. Gifford - http://www.aarongifford.com/
+# Copyright:: Copyright (c) 2009-2010, InfoWest, Inc.
+# License::   BSD license
+#--
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, the above list of authors and contributors, this list of
+#    conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. Neither the name of the author(s) or copyright holder(s) nor the
+#    names of any contributors may be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S), AUTHOR(S) AND
+# CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+# AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
+# IN NO EVENT SHALL THE COPYRIGHT HOLDER(S), AUTHOR(S), OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# DCONSEQUENTIAL AMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+# THE POSSIBILITY OF SUCH DAMAGE.
+########################################################################
+$LOAD_PATH.unshift(File.dirname(__FILE__)+'/../lib')
+
+require 'rubygems'
+require 'mtik'
+
+unless ARGV.length == 3
+  STDERR.print("Usage: #{$0} <host> <user> <pass>\n")
+  exit(-1)
+end
+
+MTik::interactive_client(ARGV[0], ARGV[1], ARGV[2])
+

data/examples/tikcommand.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+########################################################################
+#--
+#
+# FILE:     command.rb -- Example of using the Ruby MikroTik API in Ruby
+#
+#++
+# Author::    Aaron D. Gifford - http://www.aarongifford.com/
+# Copyright:: Copyright (c) 2009-2010, InfoWest, Inc.
+# License::   BSD license
+#--
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, the above list of authors and contributors, this list of
+#    conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. Neither the name of the author(s) or copyright holder(s) nor the
+#    names of any contributors may be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S), AUTHOR(S) AND
+# CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+# AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
+# IN NO EVENT SHALL THE COPYRIGHT HOLDER(S), AUTHOR(S), OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# DCONSEQUENTIAL AMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+# THE POSSIBILITY OF SUCH DAMAGE.
+########################################################################
+$LOAD_PATH.unshift(File.dirname(__FILE__)+'/../lib')
+
+require 'rubygems'
+require 'mtik'
+
+unless ARGV.length > 3
+  STDERR.print("Usage: #{$0} <host> <user> <pass> <command> [<args>...] [<command> [<args> ...]]\n")
+  exit(-1)
+end
+
+MTik::verbose = true  ## Set how you want
+
+## Detect multiple command sequences and build an array of arrays
+## where each outer array element is a command plus arguments:
+command = Array.new
+i = 3
+while i < ARGV.length
+  if ARGV[i][0,1] == '/'  ## Command detected...
+    command << [ ARGV[i] ]
+  else
+    command[command.length-1] << ARGV[i]
+  end
+  i += 1
+end
+
+p MTik::command(
+  :host=>ARGV[0],
+  :user=>ARGV[1],
+  :pass=>ARGV[2],
+  :command=>command
+)
+

data/examples/tikfetch.rb

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+########################################################################
+#--
+#
+# FILE:     fetch.rb -- Example of using the Ruby MikroTik API in Ruby
+#
+#++
+# Author::    Aaron D. Gifford - http://www.aarongifford.com/
+# Copyright:: Copyright (c) 2009-2010, InfoWest, Inc.
+# License::   BSD license
+#--
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, the above list of authors and contributors, this list of
+#    conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. Neither the name of the author(s) or copyright holder(s) nor the
+#    names of any contributors may be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S), AUTHOR(S) AND
+# CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+# AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
+# IN NO EVENT SHALL THE COPYRIGHT HOLDER(S), AUTHOR(S), OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# DCONSEQUENTIAL AMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+# THE POSSIBILITY OF SUCH DAMAGE.
+########################################################################
+$LOAD_PATH.unshift(File.dirname(__FILE__)+'/../lib')
+
+require 'rubygems'
+require 'mtik'
+
+## Uncomment this (set $VERBOSE to true) if you want crazy verbose
+## output of all API interactions:
+#MTik::verbose = true
+
+if ARGV.length < 5 || ARGV.length % 2 != 1
+  print "Usage: #{$0} <device> <user> <pass> <url> <localfilename> [<url> <localfilename>...]\n"
+  exit
+end
+
+host = ARGV.shift
+user = ARGV.shift
+pass = ARGV.shift
+begin
+  mt = MTik::Connection.new(:host=>host, :user=>user, :pass=>pass)
+rescue Errno::ETIMEDOUT, Errno::ENETUNREACH, Errno::EHOSTUNREACH, MTik::Error => e
+  print ">>> ERROR CONNECTING: #{e}"
+  exit
+end
+
+## List all files:
+files = Hash.new
+mt.get_reply_each('/file/getall') do |req, s|
+  unless s.key?('!done')
+    files[s['name']] = true
+  end
+end
+
+while ARGV.length > 0
+  url, filename = ARGV.shift, ARGV.shift
+  if files.key?(filename)
+    print ">>> ERROR: There is a file named '#{filename}' already on the device.\n"
+  else
+    print ">>> OK: Fetching file '#{filename}' from URL '#{url}'...\n"
+    mt.fetch(url, filename) do |status, total, bytes|
+      case status
+      when 'failed'
+        print ">>> ERROR: File '#{filename}' download failed!\n"
+      when 'finished'
+        print ">>> OK: File '#{filename}' download finished.\n"
+      when 'connecting'
+        print ">>> OK: Connecting to '#{url}' to download file '#{filename}'\n"
+      when 'downloading'
+        print ">>> OK: Downloaded #{bytes} bytes of #{total} of file " +
+              "'#{filename}' " +
+              (total > 0 ? '%0.2f' % (100.0*bytes/total) : '0') +
+              "%\n"
+      else
+        print ">>> ERROR: The following trap error occured: #{status}\n"
+      end
+    end
+  end
+end
+mt.wait_all
+
+print "\n"
+print "SIZE        CREATED               FILENAME\n"
+print "====================================================================\n"
+mt.get_reply_each('/file/getall') do |req, s|
+  unless s.key?('!done')
+    print "#{(s['size']+'        ')[0,10]}  #{s['creation-time']}  #{s['name']}\n"
+  end
+end
+
+print "\n"
+
+mt.close
+

data/examples/tikjson.rb

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+########################################################################
+#--
+#
+# FILE:     json.rb -- Example of using the Ruby MikroTik API in Ruby
+#
+#++
+# Author::    Aaron D. Gifford - http://www.aarongifford.com/
+# Copyright:: Copyright (c) 2009-2010, InfoWest, Inc.
+# License::   BSD license
+#--
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, the above list of authors and contributors, this list of
+#    conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. Neither the name of the author(s) or copyright holder(s) nor the
+#    names of any contributors may be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S), AUTHOR(S) AND
+# CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+# AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
+# IN NO EVENT SHALL THE COPYRIGHT HOLDER(S), AUTHOR(S), OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# DCONSEQUENTIAL AMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+# THE POSSIBILITY OF SUCH DAMAGE.
+########################################################################
+$LOAD_PATH.unshift(File.dirname(__FILE__)+'/../lib')
+
+require 'rubygems'
+require 'mtik'
+require 'json'
+
+unless ARGV.length > 3
+  STDERR.print("Usage: #{$0} <host> <user> <pass> <command> [<args>...] [<command> [<args> ...]]\n")
+  exit(-1)
+end
+
+## Detect multiple command sequences and build an array of arrays
+## where each outer array element is a command plus arguments:
+command = Array.new
+i = 3
+while i < ARGV.length
+  if ARGV[i][0,1] == '/'  ## Command detected...
+    command << [ ARGV[i] ]
+  else
+    command[command.length-1] << ARGV[i]
+  end
+  i += 1
+end
+
+print MTik::command(
+  :host=>ARGV[0],
+  :user=>ARGV[1],
+  :pass=>ARGV[2],
+  :command=>command
+).to_json + "\n"
+

data/lib/mtik.rb

@@ -0,0 +1,244 @@
+############################################################################
+## A Ruby library implementing the Ruby MikroTik API
+############################################################################
+## Author::    Aaron D. Gifford - http://www.aarongifford.com/
+## Copyright:: Copyright (c) 2009-2010, InfoWest, Inc.
+## License::   BSD license
+##
+## Redistribution and use in source and binary forms, with or without
+## modification, are permitted provided that the following conditions
+## are met:
+## 1. Redistributions of source code must retain the above copyright
+##    notice, the above list of authors and contributors, this list of
+##    conditions and the following disclaimer.
+## 2. Redistributions in binary form must reproduce the above copyright
+##    notice, this list of conditions and the following disclaimer in the
+##    documentation and/or other materials provided with the distribution.
+## 3. Neither the name of the author(s) or copyright holder(s) nor the
+##    names of any contributors may be used to endorse or promote products
+##    derived from this software without specific prior written permission.
+##
+## THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S), AUTHOR(S) AND
+## CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+## INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+## AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
+## IN NO EVENT SHALL THE COPYRIGHT HOLDER(S), AUTHOR(S), OR CONTRIBUTORS BE
+## LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+## DCONSEQUENTIAL AMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+## SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+## INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+## CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+## ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+## THE POSSIBILITY OF SUCH DAMAGE.
+############################################################################
+module MTik
+  require 'mtik/error.rb'
+  require 'mtik/fatalerror.rb'
+  require 'mtik/timeouterror.rb'
+  require 'mtik/request.rb'
+  require 'mtik/reply.rb'
+  require 'mtik/connection.rb'
+
+  ## Default MikroTik RouterOS API TCP port:
+  PORT = 8728
+  ## Default username to use if none is specified:
+  USER = 'admin'
+  ## Default password to use if none is specified:
+  PASS = ''
+  ## Connection timeout default -- *NOT USED* 
+  CONN_TIMEOUT = 60
+  ## Command timeout -- The maximum number of seconds to wait for more
+  ## API data when expecting one or more command responses.
+  CMD_TIMEOUT  = 60
+
+  @verbose = false
+  @debug   = false
+
+  ## Access the current verbose setting (boolean)
+  def self.verbose
+    return @verbose
+  end
+
+  ## Change the current verbose setting (boolean)
+  def self.verbose=(x)
+    return @verbose = x
+  end
+
+  ## Access the current debug setting (boolean)
+  def self.debug
+    return @debug
+  end
+
+  ## Change the current debug setting (boolean)
+  def self.debug=(x)
+    return @debug = x
+  end
+
+
+  ## Act as an interactive client with the device, accepting user
+  ## input from STDIN.
+  def self.interactive_client(host, user, pass)
+    old_verbose = MTik::verbose
+    MTik::verbose = true
+    begin
+      tk = MTik::Connection.new(:host => host, :user => user, :pass => pass)
+    rescue MTik::Error, Errno::ECONNREFUSED => e
+      print "=== LOGIN ERROR: #{e.message}\n"
+      exit
+    end
+
+    while true
+      print "\nCommand (/quit to end): "
+      cmd = STDIN.gets.sub(/^\s+/, '').sub(/\s*[\r\n]*$/, '')
+      maxreply = 0
+      m = /^(\d+):/.match(cmd)
+      unless m.nil?
+        maxreply = m[1].to_i
+        cmd.sub!(/^\d+:/, '')
+      end
+      args  = cmd.split(/\s+/)
+      cmd   = args.shift
+      next if cmd == ''
+      break if cmd == '/quit'
+      unless /^(?:\/[a-zA-Z0-9]+)+$/.match(cmd)
+        print "=== INVALID COMMAND: #{cmd}\n" if MTik::debug || MTik::verbose
+        break
+      end
+      print "=== COMMAND: #{cmd}\n" if MTik::debug || MTik::verbose
+      trap  = false
+      count = 0
+      state = 0
+      begin
+        tk.send_request(false, cmd, args) do |req, sentence|
+          if sentence.key?('!trap')
+            trap = sentence
+            print "=== TRAP: '" + (trap.key?('message') ? trap['message'] : "UNKNOWN") + "'\n\n"
+          elsif sentence.key?('!re')
+            count += 1
+            ## Auto-cancel any '/tool/fetch' commands that have finished,
+            ## or commands that have received the specified number of
+            ## replies:
+            if req.state != 'cancelled' && (
+              cmd == '/tool/fetch' && sentence.key?('status') && sentence['status'] == 'finished'
+            ) || (maxreply > 0 && count == maxreply)
+              state = 2
+              req.cancel do |req, sentence|  
+                state = 1
+              end
+            end
+          elsif !sentence.key?('!done') && !sentence.key?('!fatal')
+            raise MTik::Error.new("Unknown or unexpected reply sentence type.")
+          end
+          if state == 0 && req.done?
+            state = 1
+          end
+        end
+        while state != 1
+          tk.wait_for_reply
+        end
+      rescue MTik::Error => e
+        print "=== ERROR: #{e.message}\n"
+      end
+      unless tk.connected?
+        begin
+          tk.login
+        rescue MTik::Error => e
+          print "=== LOGIN ERROR: #{e.message}\n"
+          tk.close
+          exit
+        end
+      end
+    end
+ 
+    reply = tk.get_reply('/quit')
+    unless reply[0].key?('!fatal')
+      raise MTik::Error.new("Unexpected response to '/quit' command.")
+    end
+
+    ## Extract any device-provided message from the '!fatal' response
+    ## to the /quit command:
+    print "=== SESSION TERMINATED"
+    message = ''
+    reply[0].each_key do |key|
+      next if key == '!fatal'
+      message += "'#{key}'"
+      unless reply[0][key].nil?
+        message += " => '#{reply[0][key]}'"
+      end
+    end
+    if message.length > 0
+      print ": " + message
+    else
+      print " ==="
+    end
+    print "\n\n"
+
+    unless tk.connected?
+      print "=== Disconnected ===\n\n"
+    else
+      ## In theory, this should never execute:
+      tk.close
+    end
+
+    MTik::verbose = old_verbose
+  end
+
+
+  ## An all-in-one function to instantiate, connect, send one or
+  ## more commands, retrieve the response(s), close the connection,
+  ## and return the response(s).
+  ##
+  ## *WARNING* :: If you use this call with an API command like
+  ## +/tool/fetch+ it will forever keep reading replies, never
+  ## returning.  So do _NOT_ use this with any API command that does
+  ## not complete with a "!done" with no additional interaction.
+  def self.command(args)
+    tk = MTik::Connection.new(
+      :host => args[:host],
+      :user => args[:user],
+      :pass => args[:pass],
+      :port => args[:port],
+      :conn_timeout => args[:conn_timeout],
+      :cmd_timeout  => args[:cmd_timeout]
+    )
+    cmd = args[:command]
+    replies = Array.new
+    if cmd.is_a?(String)
+      ## Single command, no arguments
+      cmd = [ [ cmd ] ]
+    elsif cmd.is_a?(Array) && !cmd[0].is_a?(Array)
+      ## Single command, possibly arguments
+      cmd = [ cmd ]
+    end
+
+    cmd.each do |c|
+      replycount = 1
+      tk.send_request(false, c[0], c[1,c.length-1]) do |req, sentence|
+        replycount += 1
+        if c[0] == '/tool/fetch'
+          if (
+            sentence.key?('status') &&
+            sentence['status'] == 'finished' &&
+            req.state != 'cancelled'
+          )
+            ## Cancel 'finished' fetch commands
+            req.cancel
+          end
+        elsif replycount >= 1000 && req.state != 'cancelled'
+          ## Auto-cancel any command after 1,000 replies:
+          req.cancel
+        end
+        if sentence.key?('!done')
+          replies.push(req.reply)
+        end
+      end
+    end
+
+    tk.wait_all ## Event loop -- wait for all commands
+    tk.get_reply('/quit')
+    tk.close
+    return replies
+  end
+
+end
+