mtik 3.1.2 → 4.0.0

data/CHANGELOG.txt

@@ -1,3 +1,18 @@
+2011-03-25 (25 MAR 2011)  VERSION 4.0.0  Aaron D. Gifford (http://www.aarongifford.com)
+ * Per user suggestion, added a new optional cancel parameter to the MTik#command()
+   method that will auto-cancel the supplied command after receiving the specified
+   number of '!re' reply sentences.  This is usful for executing a command that otherwise
+   will not terminate, but will keep sending output perpetually if not canceled.
+ * Spelling changes: :cancelled updated to :canceled   This means anyone who checked the
+   state of a request using :cancelled or 'cancelled' will need to update their code to
+   check for :canceled instead.
+ * Due to changing of spelling and adding a new parameter, I've bumped the major version
+   number to 4.x in case any users code might break.  This in spite of the fact that
+   there are no major new features added.
+ * I found 2-3 tiny bugs left over from the past change of request state from string
+   to symbol and fixed those, updated error messages to reflect state as a symbol,
+   eliminated a few redundant key?() calls, and fixed a replycounter initialization
+   typo (had set it to 1 instead of 0).
 2011-01-11 (11 JAN 2011)  VERSION 3.1.2  Aaron D. Gifford (http://www.aarongifford.com)
  * Added source file encoding comments and updated the copyright notices
  * Fixed a tiny bug in lib/mtik/connection.rb
@@ -18,7 +33,7 @@
    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
+   made for timeout seconds, the command will be canceled.  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()

data/VERSION.txt

@@ -1 +1 @@
-3.1.2
+4.0.0

data/lib/mtik.rb

@@ -53,6 +53,9 @@ module MTik
   ## API data when expecting one or more command responses.
   CMD_TIMEOUT  = 60
 
+  ## Maximum number of replies before a command is auto-canceled:
+  MAXREPLIES   = 1000
+
   @verbose = false
   @debug   = false
 
@@ -120,8 +123,8 @@ module MTik
             ## 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'
+            if req.state == :sent && (
+              cmd == '/tool/fetch' && sentence['status'] == 'finished'
             ) || (maxreply > 0 && count == maxreply)
               state = 2
               req.cancel do |r, s|  
@@ -190,12 +193,52 @@ 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 <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.
+  ## PARAMETERS:
+  ##   All parameters supplied to this method are contained in a
+  ##   single hash.  Here are available hash keys:
+  ##
+  ##     :host    => the host name or IP to connect to
+  ##     :user    => the API user ID to authenticate with
+  ##     :pass    => the API password to authenticate with
+  ##     :command => one or more API commands to execute
+  ##     :limit   => an OPTIONAL integer reply limit
+  ##
+  ## The :command parameter may be:
+  ##   * A single string representing a single API command to execute
+  ##   * An array of strings in which case the first string is the API
+  ##     command to execute and each subsequent array item is an API
+  ##     parameter or argument.
+  ##   * An array of arrays -- Multiple API command may be executed
+  ##     in sequence.  Each subarray is an array of strings containing
+  ##     an API command and zero or more parameters.
+  ##
+  ## The :limit parameter if present specifies an integer.  This parameter
+  ## is to be used whenever executing one or more API commands that do
+  ## not terminate with a '!done' response sentence, but instead keep
+  ## sending '!re' reply sentences.
+  ##
+  ## An exception is the '/tools/fetch' API command, which this method
+  ## will auto-cancel when it finishes.
+  ##
+  ## Regarding the :limit parameter:
+  ##  * If present and the integer is zero or negative, THERE WILL BE
+  ##    NO LIMIT ENFORCED on the number of replies from each API command.
+  ##    *WARNING:* If you do NOT limit the number of replies when
+  ##    executing an API command like <i>"/interface/montitor-traffic"</i>
+  ##    this method may not ever terminate and may consume memory
+  ##    buffering replies until resources are exhausted.
+  ##  * If present and a positive integer, each API command may at
+  ##    most receive the specified number of reply sentences, after which
+  ##    the command will automatically be canceled.  This is useful
+  ##    to terminate commands that would otherwise keep sending output
+  ##    forever.
+  ##  * If NOT present, or if nil, the default reply limit as contained
+  ##    in the MAXREPLIES constant will be enforced. *WARNING:* This
+  ##    default limit could be so large that this method would not
+  ##    return for a long time, waiting for the number of replies.
+  ##
+  ## Remember that the limit applies separately to each API command
+  ## executed.
   def self.command(args)
     tk = MTik::Connection.new(
       :host => args[:host],
@@ -205,6 +248,7 @@ module MTik
       :conn_timeout => args[:conn_timeout],
       :cmd_timeout  => args[:cmd_timeout]
     )
+    limit = args[:limit]  ## Optional reply limit
     cmd = args[:command]
     replies = Array.new
     if cmd.is_a?(String)
@@ -217,20 +261,18 @@ module MTik
 
     cmd.each_index do |i|
       c = cmd[i]
-      replycount = 1
+      replycount = 0
       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'
-          )
+          if sentence['status'] == 'finished' && req.state == :sent
             ## Cancel 'finished' fetch commands
             req.cancel
           end
-        elsif replycount >= 1000 && req.state != 'cancelled'
-          ## Auto-cancel any command after 1,000 replies:
+        elsif req.state == :sent && (
+          limit.nil? ? (replycount >= MAXREPLIES) : (limit > 0 && replycount >= limit)
+        )
+          ## Auto-cancel any command after the maximum number of replies:
           req.cancel
         end
         if sentence.key?('!done')
@@ -239,7 +281,7 @@ module MTik
       end
     end
 
-    tk.wait_all ## Event loop -- wait for all commands
+    tk.wait_all ## Event loop -- wait for all commands to finish
     tk.get_reply('/quit')
     tk.close
     return replies

data/lib/mtik/request.rb

@@ -242,7 +242,7 @@ class MTik::Request < Array
     if @state != :sent
       raise MTik::Error.new(
         "Method MTik::Request#cancel() called with state '#{@state}' " +
-        "(should only call when state is 'sent')"
+        "(should only call when state is :sent)"
       )
     end
     @conn.send_request(true, '/cancel', '=tag=' + @tag, &callback)
@@ -254,7 +254,7 @@ class MTik::Request < Array
     if @state != :sent
       raise MTik::Error.new(
         "Method MTik::Request#cancel() called with state '#{@state}' " +
-        "(should only call when state is 'sent')"
+        "(should only call when state is :sent)"
       )
     end
     @conn.send_request(false, '/cancel', '=tag=' + @tag, &callback)

metadata

@@ -1,34 +1,26 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: mtik
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 3
-  - 1
-  - 2
-  version: 3.1.2
+version: !ruby/object:Gem::Version
+  version: 4.0.0
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Aaron D. Gifford
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-01-11 00:00:00 -07:00
-default_executable: 
+date: 2011-03-25 00:00:00.000000000Z
 dependencies: []
-
 description: MTik implements the MikroTik RouterOS API for use in Ruby.
 email: email_not_accepted@aarongifford.com
-executables: 
+executables:
 - tikcli
 - tikcommand
 - tikfetch
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.txt
-files: 
+files:
 - CHANGELOG.txt
 - LICENSE.txt
 - README.txt
@@ -45,37 +37,28 @@ files:
 - lib/mtik/reply.rb
 - lib/mtik/request.rb
 - lib/mtik/timeouterror.rb
-has_rdoc: true
 homepage: http://www.aarongifford.com/computers/mtik/
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: mtik
-rubygems_version: 1.3.7
+rubygems_version: 1.7.2
 signing_key: 
 specification_version: 3
 summary: MTik implements the MikroTik RouterOS API for use in Ruby.
 test_files: []
-