mtik 3.0.2

data/lib/mtik/error.rb

@@ -0,0 +1,37 @@
+############################################################################
+## 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.
+############################################################################
+
+## Basic execption type raised by this code
+class MTik::Error < RuntimeError ; end
+

data/lib/mtik/fatalerror.rb

@@ -0,0 +1,37 @@
+############################################################################
+## 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.
+############################################################################
+
+## Execption raised when a '!fatal' response is received from a device
+class MTik::FatalError < MTik::Error ; end
+

data/lib/mtik/reply.rb

@@ -0,0 +1,50 @@
+############################################################################
+## 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.
+############################################################################
+
+## 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.
+class MTik::Reply < Array
+  def find_sentence(key)
+    i = 0
+    while i < self.length
+      if self[i].key?(key)
+        return self[i]
+      end
+      i += 1
+    end
+    return nil
+  end
+end
+

data/lib/mtik/request.rb

@@ -0,0 +1,265 @@
+############################################################################
+## 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.
+############################################################################
+
+## 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.
+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).
+  def initialize(await_completion, command, *args, &callback)
+    @reply            = MTik::Reply.new
+    @command          = command
+    @await_completion = await_completion
+    @state            = 'new'  ## 'new', 'sent', 'cancelled', 'complete'
+    @conn             = nil
+
+    args.flatten!
+    @callbacks = Array.new
+    if block_given?
+      @callbacks.push(callback)
+    elsif args.length > 0 && args[args.length-1].is_a?(Proc)
+      @callbacks.push(args.pop)
+    end
+
+    super(&nil)
+    ## Add command to the request sentence list:
+    self.push(command)
+
+    ## Add all arguments to the request sentence list:
+    self.addargs(*args)
+
+    ## Append a unique tag for the request:
+    @tag = @@tagspace.to_s
+    @@tagspace += 1
+    self.push(".tag=#{@tag}")
+  end
+
+  ## Add one or more callback Procs and/or a code block
+  ## to the callback(s) that will be executed upon reply
+  ## (either complete or partial, depending on the
+  ## _await_completion_ setting)
+  def append_callback(*callbacks, &callback)
+    callbacks.flatten!
+    callbacks.each do |cb|
+      @callbacks.push(cb)
+    end
+    if block_given?
+      @callbacks.push(callback)
+    end
+  end
+
+  ## Append one or more arguments to the not-yet-sent request
+  def addargs(*args)
+    ## Add all additional arguments to the request sentence list:
+    args.each do |arg|
+      if arg.is_a?(Hash)
+        ## Prepend argument keys that don't begin with the API-
+        ## command-specific parameter character '.', nor the
+        ## normal parameter charactre '=', nor the query character
+        ## '?' with the ordinary parameter character '=':
+        arg.each do |key, value|
+          key = '=' + key unless /^[\?\=\.]/.match(key)
+          addarg(key + '=' + value)
+        end
+      else
+        addarg(arg)
+      end
+    end
+  end
+
+  ## Append a single argument to the not-yet-sent request
+  def addarg(arg)
+    unless /^\.tag=/.match(arg)
+      self.push(arg)
+    end
+  end
+
+  ## Return the boolean completion status of the request,
+  ## _true_ if complete, _false_ if not-yet-complete.
+  def done?
+    return @state == 'complete'
+  end
+
+  attr_reader :command, :tag, :await_completion, :reply, :state
+
+  ## Execute all callbacks, passing _sentence_ along as
+  ## the second parameter to each callback.
+  def callback(sentence)
+    case @callbacks.length
+    when 0
+      return nil
+    when 1
+      return @callbacks[0].call(self, sentence)
+    else
+      result = Array.new
+      @callbacks.each do |cb|
+        result.push(cb.call(self, sentence))
+      end
+      return result
+    end
+  end
+
+  ## Utility method for packing an unsigned integer as
+  ## a binary byte string of variable length
+  def self.bytepack(num)
+    s = String.new
+    if RUBY_VERSIION >= '1.9.0'
+      s.force_encoding(Encoding::BINARY)
+    end
+    x = num < 0 ? -num : num  ## Treat as unsigned
+    while x > 0
+      s += (x & 0xff).chr
+      x >>= 8
+    end
+    return s
+  end
+
+  ## Another utility method to encode a byte string as a
+  ## valid API _"word"_
+  def self.to_tikword(str)
+    str = str.dup
+    if RUBY_VERSION >= '1.9.0'
+      str.force_encoding(Encoding::BINARY)
+    end
+    if str.length < 0x80
+      return str.length.chr + str
+    elsif str.length < 0x4000
+      return bytepack(str.length | 0x8000) + str
+    elsif str.length < 0x200000
+      return bytepack(str.length | 0xc00000) + str
+    elsif str.length < 0x10000000
+      return bytepack(str.length | 0xe0000000) + str
+    elsif str.length < 0x0100000000
+      return 0xf0.chr + bytepack(str.length) + str
+    else
+      raise RuntimeError.new(
+        "String is too long to be encoded for " +
+        "the MikroTik API using a 4-byte length!"
+      )
+    end
+  end
+
+  ## Associate this request with a connection:
+  def conn(c)
+    unless c.is_a?(MTik::Connection)
+      raise RuntimeError.new(
+        "Unexpected class '#{c.class}' in MTik::Request#conn() " +
+        "(expected MTik::Connection)"
+      )
+    end
+    unless @conn.nil?
+      raise MTik::Error.new(
+        "Method MTik::Request#conn() called when MTik::Request " +
+        "is already associated with an MTik::Connection object."
+      )
+    end
+    @conn = c
+  end
+
+  ## Encode this request as a binary byte string ready for transmission
+  ## to a MikroTik device
+  def request
+    ## Encode the request for sending to the device:
+    return self.map {|w| MTik::Request::to_tikword(w)}.join + 0x00.chr
+  end
+
+  ## Send the request over the associated connection:
+  def send
+    if @conn.nil?
+      raise MTik::Error.new(
+        "Method MTik::Request#send() called when MTik::Request " +
+        "is not yet associated with an MTik::Connection object."
+      )
+    end
+    @state = 'sent'
+    return @conn.xmit(self)
+  end
+
+  ## Cancel a 'sent' request:
+  def cancel(&callback)
+    if @state != 'sent'
+      raise MTik::Error.new(
+        "Method MTik::Request#cancel() called with state '#{@state}' " +
+        "(should only call when state is 'sent')"
+      )
+    end
+    @conn.send_request(true, '/cancel', '=tag=' + @tag, &callback)
+    @state = 'cancelled'
+  end
+
+  ## Cancel a 'sent' request:
+  def cancel_each(&callback)
+    if @state != 'sent'
+      raise MTik::Error.new(
+        "Method MTik::Request#cancel() called with state '#{@state}' " +
+        "(should only call when state is 'sent')"
+      )
+    end
+    @conn.send_request(false, '/cancel', '=tag=' + @tag, &callback)
+    @state = 'cancelled'
+  end
+
+  ## Method the internal parser calls to flag this reply as completed
+  ## upon receipt of a +!done+ reply sentence.
+  def done!
+    @state = 'complete'
+    return true
+  end
+end
+

data/lib/mtik/timeouterror.rb

@@ -0,0 +1,37 @@
+############################################################################
+## 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.
+############################################################################
+
+## Exception raised upon timeout
+class MTik::TimeoutError < MTik::Error ; end
+

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: mtik
+version: !ruby/object:Gem::Version 
+  version: 3.0.2
+platform: ruby
+authors: 
+- Aaron D. Gifford
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-05 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: MTik implements the MikroTik RouterOS API for use in Ruby.
+email: email_not_accepted@aarongifford.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.txt
+files: 
+- CHANGELOG.txt
+- LICENSE.txt
+- README.txt
+- VERSION.txt
+- examples/tikcli.rb
+- examples/tikcommand.rb
+- examples/tikfetch.rb
+- examples/tikjson.rb
+- lib/mtik.rb
+- lib/mtik/connection.rb
+- lib/mtik/error.rb
+- lib/mtik/fatalerror.rb
+- lib/mtik/reply.rb
+- lib/mtik/request.rb
+- lib/mtik/timeouterror.rb
+has_rdoc: true
+homepage: http://www.aarongifford.com/computers/mtik/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: mtik
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: MTik implements the MikroTik RouterOS API for use in Ruby.
+test_files: []
+