mtik 3.0.5 → 3.1.0

data/CHANGELOG.txt

@@ -1,3 +1,17 @@
+2010-04-24 (24 APR 2010)  VERSION 3.1.0  Aaron D. Gifford (http://www.aarongifford.com)
+ * Added find_sentences() method to MTik::Reply -- just sugar to Array.select()
+ * Changed MTik::Connection.fetch() method to add an optional timeout parameter
+   which should not affect the API and should be backward compatible.  By default,
+   there is no inactivity timeout for downloads.  But if you set the timeout parameter
+   to a positive number, when a reply arrives and no progress/activity has been
+   made for timeout seconds, the command will be cancelled.  This should help with
+   stalled downloads (i.e. the remote side has stopped sending but the TCP connection
+   remains open/active).
+ * Also add the MTik::Request object as a parameter to the MTik::Connection.fetch()
+   method's callback so that a script could use the request object to cancel the
+   command if needed.  Due to this change, I decided to bump the version to 3.1.0.
+ * Fixed RDoc formatting in several files, and added an RDocTask to the Rakefile
+
 2010-04-23 (23 APR 2010)  VERSION 3.0.5  Aaron D. Gifford (http://www.aarongifford.com)
  * Double bug-fix (typo fix and logic fix) to request.rb thanks to Allan Eising and 
    Søren Daugaard.  Thank you both for the patch!

data/README.txt

@@ -43,7 +43,7 @@ For documentation on the MikroTik RouterOS APi, see
 
 To install MTik is through its GEM file:
 
-  % [sudo] gem install mtik-3.3.0.gem
+  % [sudo] gem install mtik-3.1.0.gem
 
 == License
 

data/Rakefile

@@ -1,5 +1,6 @@
 require 'rubygems'
 require 'rake/gempackagetask'
+require 'rake/rdoctask'
 
 gemspec = Gem::Specification.new do |spec|
   spec.name         = 'mtik'
@@ -39,5 +40,15 @@ Rake::GemPackageTask.new(gemspec) do |pkg|
   pkg.need_tar = true
 end
 
-task :default => [ 'pkg/mtik-'  + File.open('VERSION.txt','r').to_a.join.strip + '.gem' ]
+Rake::RDocTask.new do |rdoc|
+  rdoc.name     = 'rdoc'
+  rdoc.main     = 'README.txt'
+  rdoc.rdoc_dir = 'doc'
+  rdoc.rdoc_files.include('README.txt', 'LICENSE.txt', 'CHANGELOG.txt', 'lib/**/*.rb')
+end
+
+task :default => [
+  'pkg/mtik-' + File.open('VERSION.txt','r').to_a.join.strip + '.gem',
+  :rdoc
+]
 

data/VERSION.txt

@@ -1 +1 @@
-3.0.5
+3.1.0

data/examples/tikfetch.rb

@@ -73,7 +73,7 @@ while ARGV.length > 0
     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|
+    mt.fetch(url, filename, 120) do |status, total, bytes, req|
       case status
       when 'failed'
         print ">>> ERROR: File '#{filename}' download failed!\n"

data/lib/mtik.rb

@@ -188,10 +188,12 @@ module MTik
   ## 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.
+  ## *WARNING*:
+  ## If you use this call with an API command like <i>"/tool/fetch"</i>
+  ## or a similar command that generates replies until canceled,
+  ## it will forever keep reading replies, never returning.  So do
+  ## _NOT_ use this with any API command that does not complete with
+  ## a <i>"!done"</i> response without any additional interaction.
   def self.command(args)
     tk = MTik::Connection.new(
       :host => args[:host],

data/lib/mtik/connection.rb

@@ -43,16 +43,16 @@ class MTik::Connection
   ## key/value pair style arguments must be specified. The one
   ## required argument is the host or IP of the device to connect
   ## to.
-  ##  _host_ :: This is the only _required_ argument. Example:
-  ##            + :host => "rb411.example.org" +
-  ##  _port_ :: Override the default API port (8728)
-  ##  _user_ :: Override the default API username ('admin')
-  ##  _pass_ :: Override the default API password (blank)
-  ##  _conn_timeout_ :: Override the default connection
-  ##                    timeout (60 seconds) -- *NOT USED*
-  ##  _cmd_timeout_ ::  Override the default command timeout
-  ##                    (60 seconds) -- the number of seconds
-  ##                    to wait for additional API input.
+  ## +host+:: This is the only _required_ argument. Example:
+  ##          <i> :host => "rb411.example.org" </i>
+  ## +port+:: Override the default API port (8728)
+  ## +user+:: Override the default API username ('admin')
+  ## +pass+:: Override the default API password (blank)
+  ## +conn_timeout+:: Override the default connection
+  ##                  timeout (60 seconds) -- *NOT USED*
+  ## +cmd_timeout+::  Override the default command timeout
+  ##                  (60 seconds) -- the number of seconds
+  ##                  to wait for additional API input.
   def initialize(args)
     @sock         = nil
     @requests     = Hash.new
@@ -321,18 +321,18 @@ class MTik::Connection
   end
 
   ## Send a request to the device.
-  ##   +await_completion+ ::  Boolean indicating whether to execute callbacks
-  ##                          only once upon request completion (if set to _true_)
-  ##                          or to execute for every received complete sentence
-  ##                          (if set to _false_).  ALTERNATIVELY, this parameter
-  ##                          may be an object (MTik::Request) to be sent, in which
-  ##                          case any command and/or arguments will be treated as
-  ##                          additional arguments to the request contained in the
-  ##                          object.
-  ##   +command+ ::           The command to be executed.
-  ##   +args+ ::              Zero or more arguments to the command
-  ##   +callback+ ::          Proc/lambda code (or code block if not provided as
-  ##                          an argument) to be called.  (See the +await_completion+
+  ## +await_completion+::  Boolean indicating whether to execute callbacks
+  ##                       only once upon request completion (if set to _true_)
+  ##                       or to execute for every received complete sentence
+  ##                       (if set to _false_).  ALTERNATIVELY, this parameter
+  ##                       may be an object (MTik::Request) to be sent, in which
+  ##                       case any command and/or arguments will be treated as
+  ##                       additional arguments to the request contained in the
+  ##                       object.
+  ## +command+::           The command to be executed.
+  ## +args+::              Zero or more arguments to the command
+  ## +callback+::          Proc/lambda code (or code block if not provided as
+  ##                       an argument) to be called.  (See the +await_completion+
   ##                    
   def send_request(await_completion, command, *args, &callback)
     if await_completion.is_a?(MTik::Request)
@@ -367,18 +367,19 @@ class MTik::Connection
 
   ## Send a command, then wait for the command to complete, then return
   ## the completed reply.
-  ## _NOTE_ :: This call has its own event loop that will cycle
-  ##           until the command in question completes.  You
-  ##           should:
-  ##             * NOT call get_reply with a command that may not
-  ##               complete with a "!done" response on its own
-  ##               (with no additional intervention); and
-  ##             * BE CAREFUL to understand how things interact if
-  ##               you mix this call with requests that generate
-  ##               continuous output.
-  ## +command+ ::  The command to execute
-  ## +args+ ::     Arguments (if any)
-  ## +callback+ :: Proc/lambda or code block to act as callback
+  ##
+  ## +command+::  The command to execute
+  ## +args+::     Arguments (if any)
+  ## +callback+:: Proc/lambda or code block to act as callback
+  ##
+  ## *NOTE*: This call has its own event loop that will cycle until
+  ## the command in question completes. You should:
+  ## * NOT call get_reply with a command that may not
+  ##   complete with a "!done" response on its own
+  ##   (with no additional intervention); and
+  ## * BE CAREFUL to understand how things interact if
+  ##   you mix this call with requests that generate
+  ##   continuous output.
   def get_reply(command, *args, &callback)
     req = send_request(true, command, *args, &callback)
     wait_for_request(req)
@@ -483,20 +484,29 @@ class MTik::Connection
   ## Utility to execute the "/tool/fetch" command, instructing
   ## the device to download a file from the specified URL.
   ## Status updates are provided via the provided callback.
-  ##   _url_ ::      The URL to fetch the file from
-  ##   _filename_ :: The filename to use on the device
-  ##   _callback_ :: Callback called for status updates. The three
-  ##                 arguments passed to the callback are:
-  ##                   _status_ :: Either 'downloading', 'connecting',
-  ##                               'failed', 'requesting', or 'finished',
-  ##                               otherwise a '!trap' error occured,
-  ##                               and the value is the trap message.
-  ##                   _total_ ::  Final expected file size in bytes
-  ##                   _bytes_ ::  Number of bytes transferred so far
-  def fetch(url, filename, &callback)
-    total  = bytes = 0
+  ## +url+::      The URL to fetch the file from
+  ## +filename+:: The filename to use on the device
+  ## +timeout+::  Cancel command if a reply indicates the
+  ##              download has stalled for +timeout+ seconds.
+  ##              This is disabled by default. Disable by
+  ##              setting +timeout+ to nil or zero, enable by
+  ##              supplying a positive number of seconds.
+  ##              (OPTIONAL argument)
+  ## +callback+:: Callback called for status updates.
+  ##
+  ## The arguments passed to the callback are:
+  ## +status+::   Either 'downloading', 'connecting',
+  ##              'failed', 'requesting', or 'finished',
+  ##              otherwise a '!trap' error occured,
+  ##              and the value is the trap message.
+  ## +total+::    Final expected file size in bytes
+  ## +bytes+::    Number of bytes transferred so far
+  ## +request+::  The MTik::Request object
+  def fetch(url, filename, timeout=nil, &callback)
+    total  = bytes = oldbytes = 0
     status = ''
     done   = false
+    lastactivity = Time.now
     req = get_reply_each(
       '/tool/fetch',
       '=url=' + url,
@@ -511,12 +521,18 @@ class MTik::Connection
         when 'downloading'
           total = s['total'].to_i
           bytes = s['downloaded'].to_i
-          callback.call(status, total, bytes)
+          if bytes != oldbytes
+            lastactivity = Time.now
+          elsif timeout != 0 && !timeout.nil? && Time.now - lastactivity > timeout
+            ## Cancel the request (idle too long):
+            get_reply('/cancel', '=tag=' + req.tag) {}
+          end
+          callback.call(status, total, bytes, req)
         when 'connecting', 'requesting'
-          callback.call(status, 0, 0)
+          callback.call(status, 0, 0, req)
         when 'failed', 'finished'
           bytes = total if status == 'finished'
-          callback.call(status, total, bytes)
+          callback.call(status, total, bytes, req)
           done = true
           ## Now terminate the download request (since it's done):
           get_reply('/cancel', '=tag=' + req.tag) {}
@@ -526,7 +542,7 @@ class MTik::Connection
       elsif s.key?('!trap')
         ## Pass trap message back (unless finished--in which case we
         ## ignore the 'interrrupted' trap message):
-        callback.call(s['message'], total, bytes) if !done
+        callback.call(s['message'], total, bytes, req) if !done
       end
     end
   end

data/lib/mtik/fatalerror.rb

@@ -32,6 +32,6 @@
 ## THE POSSIBILITY OF SUCH DAMAGE.
 ############################################################################
 
-## Execption raised when a '!fatal' response is received from a device
+## Execption raised when a <i>"!fatal"</i> response is received from a device
 class MTik::FatalError < MTik::Error ; end
 

data/lib/mtik/reply.rb

@@ -34,17 +34,23 @@
 
 ## A MikroTik API reply is stored as an array of response sentences. Each
 ## sentence is a key/value Hash object. The MTik::Reply class is simply
-## a basic Ruby Array with a find_sentence method added.
+## a basic Ruby Array with find_sentence and find_sentences methods added.
 class MTik::Reply < Array
+  ## This method is nearly identical to Array.select{|i| i.key?(key)}[0]
+  ## except that this method short-circuits and returns when the first
+  ## match is found.
   def find_sentence(key)
-    i = 0
-    while i < self.length
-      if self[i].key?(key)
-        return self[i]
-      end
-      i += 1
+    self.each do |sentence|
+      return sentence if sentence.key?(key)
     end
     return nil
   end
+
+  ## This method is simply an alias for Array.select{|i| i.key?(key)}
+  def find_sentences(key)
+    return self.select do |sentence|
+      sentence.key?(key)
+    end
+  end
 end
 

data/lib/mtik/request.rb

@@ -35,33 +35,34 @@
 ## A MikroTik API request object is stored as an array of MikroTik
 ## API-style words, the first word being the command, subsequent words
 ## (if any) are command arguments.  Each request will automatically
-## have a unique tag generated (so any +.tag=value+ arguments will be
-## ignored). A request is incomplete until the final +!done+ response
-## sentence has been received.
+## have a unique tag generated (so any <i>".tag=value"</i> arguments
+## will be ignored). A request is incomplete until the final
+## <i>"!done"</i> response sentence has been received.
 class MTik::Request < Array
   @@tagspace = 0  ## Used to keep all tags unique.
 
   ## Create a new MTik::Request.
-  ## +await_completion+ :: A boolean parameter indicating when callback(s)
-  ##                    should be called.  A value of _true_ will result
-  ##                    in callback(s) only being called once, when the
-  ##                    final +!done+ response is received.  A value of
-  ##                    _false_ means callback(s) will be called _each_
-  ##                    time a response sentence is received.
-  ## +command+ ::       The MikroTik API command to execute (a String).
-  ##                    Examples:
-  ##                      * +"/interface/getall"+
-  ##                      * +"/ip/route/add"+
-  ## +args+ ::          Zero or more String arguments for the command,
-  ##                    already encoded in +"=key=value"+, +".id=value"+
-  ##                    or +"?query"+ API format.
-  ## +callback+::       A Proc or code block may be passed which will
-  ##                    be called with two arguments:
-  ##                     1. this MTik::Request object; and
-  ##                     2. the most recently received response sentence.
-  ##                    When or how often callbacks are called depends on
-  ##                    whether the +await_completion+ parameter is _true_
-  ##                    or _false_ (see above).
+  ## +await_completion+:: A boolean parameter indicating when callback(s)
+  ##                      should be called.  A value of _true_ will result
+  ##                      in callback(s) only being called once, when the
+  ##                      final +!done+ response is received.  A value of
+  ##                      _false_ means callback(s) will be called _each_
+  ##                      time a response sentence is received.
+  ## +command+::          The MikroTik API command to execute (a String).
+  ##                      Examples:
+  ##                        "/interface/getall"
+  ##                        "/ip/route/add"
+  ## +args+::             Zero or more String arguments for the command,
+  ##                      already encoded in <i>"=key=value"</i>,
+  ##                      <i>".id=value"</i>, or <i>"?query"</i> API
+  ##                      format.
+  ## +callback+::         A Proc or code block may be passed which will
+  ##                      be called with two arguments:
+  ##                      1. this MTik::Request object; and
+  ##                      2. the most recently received response sentence.
+  ##                      When or how often callbacks are called depends on
+  ##                      whether the +await_completion+ parameter is _true_
+  ##                      or _false_ (see above).
   def initialize(await_completion, command, *args, &callback)
     @reply            = MTik::Reply.new
     @command          = command
@@ -175,7 +176,7 @@ class MTik::Request < Array
   end
 
   ## Another utility method to encode a byte string as a
-  ## valid API _"word"_
+  ## valid API <i>"word"</i>
   def self.to_tikword(str)
     str = str.dup
     if RUBY_VERSION >= '1.9.0'
@@ -260,7 +261,7 @@ class MTik::Request < Array
   end
 
   ## Method the internal parser calls to flag this reply as completed
-  ## upon receipt of a +!done+ reply sentence.
+  ## upon receipt of a <i>"!done"</i> reply sentence.
   def done!
     @state = 'complete'
     return true

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 3
+  - 1
   - 0
-  - 5
-  version: 3.0.5
+  version: 3.1.0
 platform: ruby
 authors: 
 - Aaron D. Gifford