opensips-mi 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MjczNzYxY2E2ZWRkNjEwOWFiYThmNmQ2YTU1YTA2MzBlMjZlZDYzNg==
+  data.tar.gz: !binary |-
+    MjIwNDQwZTk0NTY4NDVmNmJjODM0ZjBiYTRiNDVmNzExODVhNGY1MQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    YThmNzdmNzRkNmZiOTdlMWE2NDJkZWZhMTU4MTEzNGU1MDMzNjlmNGVkMmY3
+    ZGEyZTJjYWQyOTg0OTA4YTIyYTg1OTczNTI4MzExNTNlYWM5NzRiMTkwOTQz
+    Mzg1ZjM1ODYyZTdiZDcwMmM0NmUxMzgxNWI2OTAyNDMxOWY1Y2Y=
+  data.tar.gz: !binary |-
+    YzMwZTc1OWNjM2FkYTZmY2ZhOTk0YmQzNDJlN2JjNzI0OGU0YTcyMjE5ZTBj
+    ZmFiYmU1ZmRhMTRkODg5NjhmM2MzNTMyNmJiMDk1MTJhNjM5OWI5MjMwZDdh
+    NmJhYWNiODBkZTZlYzdmNzYyYTBhNzI3ZWI0YTE5YmY4YTRmNjQ=

data/.gitignore

@@ -0,0 +1,28 @@
+# Ignore temporary files
+.*swp
+*~
+
+*.gem
+*.rbc
+Gemfile*.lock
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/
+
+.DS_Store
+results.html
+html
+

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+gemspec
+
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Stas Kobzar
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,275 @@
+# Opensips::Mi
+
+OpenSIPs management interface API. 
+This library support following management interface OpenSIPs modules:
+
+* mi_fifo
+* mi_datagram
+* mi_xmlrpc
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'opensips-mi'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install opensips-mi
+
+## Connecting management interfaces
+
+### Generic connection interface
+
+Using generic function to connect management interface:
+```ruby
+require 'opensips-mi'
+Opensips::MI.connect INTERFACE, PARAMS
+```
+Parameters:
+
+*INTRFACE* - interface key. One of the following:
+
+* :fifo
+* :datagram
+* :xmlrpc
+
+*PARAMS* - connection parameters. Depends on interface. See below.
+
+This function will raise exceptions if there are parameters or environment errors.
+Function returns instance of one of the following classes:
+
+* Opensips::MI::Transport::Fifo
+* Opensips::MI::Transport::Datagram
+* Opensips::MI::Transport::Xmlrpc
+
+### FIFO
+
+```ruby
+require 'opensips-mi'
+opensips = Opensips::MI.connect :fifo, 
+                                :fifo_name => '/tmp/opensips_fifo',
+                                :reply_fifo => 'opensips_reply' . $$,
+                                :reply_dir => '/tmp'
+
+```
+
+**Parameters hash:** 
+
+* fifo_name: OpenSIPs fifo file. See mi_fifo module parameter: `modparam("mi_fifo", "fifo_name", "/tmp/opensips_fifo")`.
+* reply_fifo: (OPTIONAL) Name of the reply fifo file. If not used will generate random file in *reply_dir* and delete after use.
+* reply_dir:  (OPTIONAL) Path to directory of reply fifo file.
+
+### Datagram
+```ruby
+require 'opensips-mi'
+opensips = Opensips::MI.connect :datagram, 
+                                :host => "sipproxy.com", 
+                                :port => 8809
+```
+**Parameters hash:**
+
+* host: Hostname or IP address of OpenSIPs server
+* port: Datagram port. See mi_datagram module configuration parameter: `modparam("mi_datagram", "socket_name", "udp:192.168.2.133:8809")`
+
+### XMLRPC
+```ruby
+require 'opensips-mi'
+opensips = Opensips::MI.connect :xmlrpc, 
+                                :host => "192.168.122.128", 
+                                :port => 8080
+```
+**Parameters hash:**
+
+* host: Hostname or IP address of OpenSIPs server
+* port: Datagram port. See mi_xmlrpc module configuration parameter: `modparam("mi_xmlrpc", "port", 8080)`
+
+### Command function
+
+Function "*command*" expects fifo command as first argument following by command parameters.
+For example:
+
+```ruby
+require 'opensips-mi'
+opensips = Opensips::MI.connect :fifo, 
+                                :fifo_name => '/tmp/opensips_fifo'
+                                
+opensips.command('which')
+opensips.command('get_statistics', 'dialog','tm')
+```
+
+### Command method interface
+
+It is also possible to use command names as a method interface:
+```ruby
+require 'opensips-mi'
+opensips = Opensips::MI.connect :datagram, 
+                                :host => "192.168.122.128", 
+                                :port => 8809
+                                
+opensips.which
+opensips.get_statistics('dialog','tm')
+opensips.uptime
+opensips.ul_show_contact('location', 'alice')
+```
+
+Such methods first check if fifo function exists against `which` fifo command. 
+
+### Response
+
+Command function returns `Opensips::MI::Response` class. This class containe following class members which can be used to process responses:
+
+* code: *Integer* Response code: 200, 404 etc
+* message: *String* Response messages: "OK", "Bad headers"
+* rawdata: *Array* Raw response data as array
+* result: *Mixed* Struct/Hash/Array/Nil. This is member used by helper response methods for pretty formated result. See below.
+ 
+### Response helpers methods
+
+There are several helper methods which return conveniently formatted data:
+* ul_dump
+* uptime
+* cache_fetch
+* ul_show_contact
+* dlg_list
+
+See example files for details.
+
+## Dialog methods
+
+Dialog methods are interface to `t_uac_dlg` function of OpenSIPs' *tm* (transactions) module. 
+Module generates and sends a local SIP request.
+
+### Interface to t_uac_dlg function of transaction (tm) module
+Very cool method from OpenSIPs. Can generate and send SIP request method to destination.
+Example of usage:
+* Send NOTIFY with special Event header to force restart SIP phone (equivalent of ASterisk's "sip notify peer")
+* Send PUBLISH to trigger device state change notification
+* Send REFER to transfer call
+* etc., etc., etc.
+
+**Headers***
+Headers parameter "hf" is a hash of headers of format:
+```
+header-name => header-value
+```
+Example:
+```
+hf["From"] => "Alice Liddell <sip:alice@wanderland.com>;tag=843887163"
+```
+
+Special "nl" header with any value is used to input additional "\r\n". This is
+useful, for example, for message-summary event to separate application body. This is
+because t_uac_dlg expect body parameter as xml only.
+
+Thus, using multiple headers with same header-name is not possible with header hash.
+However, it is possible to use multiple header-values comma separated (rfc3261, section 7.3.1):
+```
+hf["Route"] => "<sip:alice@atlanta.com>, <sip:bob@biloxi.com>"
+```
+Is equivalent to:
+```
+Route: <sip:alice@atlanta.com>
+Route: <sip:bob@biloxi.com>
+```
+If there is headers To and From not found, then exception ArgumentError is raised. Also if
+body part present, Content-Type and Content-length are also mandatory and exception is raised.
+
+**Parameters**
+* method:     SIP request method (NOTIFY, PUBLISH etc)
+* ruri:       Request URI, ex.: sip:555@10.0.0.55:5060
+* hf:         Headers array. Additional headers will be added to request. At least "From" and "To" headers must be specify.
+* nhop:       Next hop SIP URI (OBP); use "." if no value.
+* socket:     Local socket to be used for sending the request; use "." if no value. Ex.: udp:10.130.8.21:5060
+* body:       (optional, may not be present) request body (if present, requires the "Content-Type" and "Content-length" headers)
+
+**Example of usage**
+```ruby
+opensips.uac_dlg "NOTIFY", "sip:alice@127.0.0.1:5066", 
+                  {
+                    "From"  => "<sip:alice@wanderland.com>;tag=8755a8d01a12f7e903a6f4ccaf393f04",
+                    "To"    => "<sip:alice@wanderland.com>",
+                    "Event" => "check-sync"
+                  }
+```
+
+### NOTIFY check-sync like event
+NOTIFY Events to restart phone, force configuration reload or 
+report for some SIP IP phone models. 
+The events list was taken from Asterisk configuration file (sip_notify.conf)
+Note that SIP IP phones usually should be configured to accept special notify
+event to reboot. For example, Polycom configuration option to enable special
+event would be:
+```  
+  voIpProt.SIP.specialEvent.checkSync.alwaysReboot="1"
+```
+This function will generate To/From/Event headers. Will use random tag for 
+From header. 
+*NOTE*: This function will not generate To header tag. This is not complying with
+SIP protocol specification (rfc3265). NOTIFY must be part of a subscription 
+dialog. However, it works for the most of the SIP IP phone models.
+**Parameters**
+* uri:    Valid client contact URI (sip:alice@10.0.0.100:5060). To get client URI use *ul_show_contact => contact* function
+* event:  One of the events from EVENTNOTIFY constant hash
+* hf:     Header fields. Add To/From header fields here if you do not want them to be auto-generated. Header field example: `hf['To'] => '<sip:alice@wanderland.com>'`
+
+**Example of usage**
+Will reboot Polycom phone:
+```ruby
+opensips.event_notify 'sip:alice@127.0.0.1:5060', :polycom_check_cfg
+```
+
+**List of available events' keys:**
+
+* :astra_check_cfg
+* :aastra_xml
+* :digium_check_cfg
+* :linksys_cold_restart
+* :linksys_warm_restart
+* :polycom_check_cfg
+* :sipura_check_cfg
+* :sipura_get_report
+* :snom_check_cfg
+* :snom_reboot
+* :cisco_check_cfg
+* :avaya_check_cfg
+
+### Presence MWI
+
+Send message-summary NOTIFY Event to update phone voicemail status.
+
+**Parameters**
+
+* uri:      Request URI (sip:alice@wanderland.com:5060). To get client URI use *ul_show_contact => contact* function
+* vmaccount:Message Account value. Ex.: sip:*97@asterisk.com
+* new:      Number of new messages. If more than 0 then Messages-Waiting header will be "yes". Set to 0 to clear phone MWI
+* old:      (optional) Old messages
+* urg_new:  (optional) New urgent messages
+* urg_old:  (optional) Old urgent messages
+
+**Example of usage**
+```ruby
+opensips.mwi_update 'sip:alice@wanderland.com:5060', 'sip:*97@voicemail.pbx.com', 5
+```
+
+## Examples
+
+There are some sample files in *examples* directory.
+
+## TODO:
+
+Support for mi_xmlrpc_ng
+
+----
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+

data/Rakefile

@@ -0,0 +1,20 @@
+require "bundler/gem_tasks"
+require "rake/clean"
+require 'opensips/mi/version'
+
+require "rdoc/task"
+Rake::RDocTask.new do |rd|
+  rd.rdoc_dir = 'rdoc'
+  rd.main = "README.md"
+  rd.rdoc_files.include("README.md","lib/**/*.rb")
+  rd.title = "OpenSIPs management interface " << Opensips::MI::VERSION
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  #test.verbose = true
+end
+
+task :default => :test

data/lib/opensips.rb

@@ -0,0 +1,4 @@
+require "opensips/mi"
+
+module Opensips
+end

data/lib/opensips/mi.rb

@@ -0,0 +1,23 @@
+require 'ostruct'
+require 'fcntl'
+require 'securerandom'
+require 'socket'
+require 'xmlrpc/client'
+
+require "opensips/mi/version"
+require "opensips/mi/response"
+require "opensips/mi/command"
+require "opensips/mi/transport"
+
+module Opensips
+  module MI
+    def self.connect(transport, params)
+      class_name = transport.to_s.capitalize
+      # send to transport class
+      Transport.const_get(class_name).init params
+    rescue NameError => e
+      raise NameError, "Unknown transport method: " << transport.to_s
+    end
+  end
+end
+

data/lib/opensips/mi/command.rb

@@ -0,0 +1,167 @@
+module Opensips
+  module MI
+    class Command
+      EVENTNOTIFY = {
+        # Aastra
+        aastra_check_cfg:       'check-sync',
+        aastra_xml:             'aastra-xml',
+        # Digium
+        digium_check_cfg:       'check-sync',
+        # Linksys
+        linksys_cold_restart:   'reboot_now',
+        linksys_warm_restart:   'restart_now',
+        # Polycom
+        polycom_check_cfg:      'check-sync',
+        # Sipura
+        sipura_check_cfg:       'resync',
+        sipura_get_report:      'report',
+        # Snom
+        snom_check_cfg:         'check-sync;reboot=false',
+        snom_reboot:            'check-sync;reboot=true',
+        # Cisco
+        cisco_check_cfg:        'check-sync',
+        # Avaya
+        avaya_check_cfg:        'check-sync',
+      }
+
+      # Interface to mi methods direct call
+      def method_missing(md, *params, &block)  
+        response = command 'which'
+        raise NoMethodError, 
+          "Method #{md} does not exists" unless response.rawdata.include?(md.to_s)
+        response = command md.to_s, params
+        # return special helper output if exists
+        return response unless response.success
+        if response.respond_to?(md)
+          response.send md
+        else
+          response
+        end
+      end
+
+      # = Interface to t_uac_dlg function of transaction (tm) module
+      # Very cool method from OpenSIPs. Can generate and send SIP request method to destination.
+      # Example of usage:
+      #   - Send NOTIFY with special Event header to force restart SIP phone (equivalent of ASterisk's "sip notify peer")
+      #   - Send PUBLISH to trigger device state change notification
+      #   - Send REFER to transfer call
+      #   - etc., etc., etc.
+      #
+      # == Headers
+      # Headers parameter "hf" is a hash of headers of format:
+      #   header-name => header-value
+      # Example:
+      #   hf["From"] => "Alice Liddell <sip:alice@wanderland.com>;tag=843887163"
+      #
+      # Special "nl" header with any value is used to input additional "\r\n". This is
+      # useful, for example, for message-summary event to separate application body. This is
+      # because t_uac_dlg expect body parameter as xml only.
+      #
+      # Thus, using multiple headers with same header-name is not possible with header hash.
+      # However, it is possible to use multiple header-values comma separated (rfc3261, section 7.3.1):
+      #   hf["Route"] => "<sip:alice@atlanta.com>, <sip:bob@biloxi.com>"
+      # Is equivalent to:
+      #   Route: <sip:alice@atlanta.com>
+      #   Route: <sip:bob@biloxi.com>
+      #
+      # If there is headers To and From not found, then exception ArgumentError is raised. Also if
+      # body part present, Content-Type and Content-length are also mandatory and exception is raised.
+      #
+      # == Parameters
+      #   method:     SIP request method (NOTIFY, PUBLISH etc)
+      #   ruri:       Request URI, ex.: sip:555@10.0.0.55:5060
+      #   hf:         Headers array. Additional headers will be added to request. 
+      #               At least "From" and "To" headers must be specify
+      #   nhop:       Next hop SIP URI (OBP); use "." if no value.
+      #   socket:     Local socket to be used for sending the request; use "." if no value. Ex.: udp:10.130.8.21:5060
+      #   body:       (optional, may not be present) request body (if present, requires the "Content-Type" and "Content-length" headers)
+      #
+      def uac_dlg method, ruri, hf, next_hop = ?., socket = ?., body = nil
+        mandatory_hf = Array['To', 'From']
+        mandatory_hf += ['Content-Type', 'Content-Length'] unless body.nil?
+        mandatory_hf.map{|h|h.downcase}.each do |n|
+          raise ArgumentError, 
+            "Missing mandatory header #{n.capitalize}" unless hf.keys.map{|h| h.downcase}.include?(n)
+        end
+        # compile headers to string
+        headers = hf.map{|name,val| name.eql?("nl") ? "" : "#{name}: #{val}"}.join "\r\n"
+        headers << "\r\n"
+        
+        # hack for xmlrpc which fails if headers are quoted
+        headers = set_header(headers) 
+        #params = [method, ruri, next_hop, socket, "\"#{headers}\""]
+        params = [method, ruri, next_hop, socket, headers]
+        params << body unless body.nil?
+        # send it and return Response
+        command 't_uac_dlg', params
+      end
+
+      # = NOTIFY check-sync like event
+      # NOTIFY Events to restart phone, force configuration reload or 
+      # report for some SIP IP phone models. 
+      # The events list was taken from Asterisk configuration file (sip_notify.conf)
+      # Note that SIP IP phones usually should be configured to accept special notify
+      # event to reboot. For example, Polycom configuration option to enable special
+      # event would be:
+      #   voIpProt.SIP.specialEvent.checkSync.alwaysReboot="1"
+      #
+      # This function will generate To/From/Event headers. Will use random tag for 
+      # From header. 
+      # *NOTE*: This function will not generate To header tag. This is not complying with
+      # SIP protocol specification (rfc3265). NOTIFY must be part of a subscription 
+      # dialog. However, it works for the most of the SIP IP phone models.
+      # == Parameters
+      #   - uri:    Valid client contact URI (sip:alice@10.0.0.100:5060). 
+      #             To get client URI use *ul_show_contact => contact* function
+      #   - event:  One of the events from EVENTNOTIFY constant hash
+      #   - hf:     Header fields. Add To/From header fields here if you do not want them 
+      #             to be auto-generated. Header field example:
+      #             hf['To'] => '<sip:alice@wanderland.com>'
+      #
+      def event_notify uri, event, hf = {}
+        raise ArgumentError,
+          "Invalid notify event: #{event.to_s}" unless EVENTNOTIFY.keys.include?(event)
+        hf['To'] = "<#{uri}>" unless hf.keys.map{|k|k.downcase}.include?('to')
+        hf['From'] = "<#{uri}>;tag=#{SecureRandom.hex}" unless hf.keys.map{|k|k.downcase}.include?('from')
+        hf['Event'] = EVENTNOTIFY[event]
+        
+        uac_dlg "NOTIFY", uri, hf
+      end
+
+      # = Presence MWI
+      # Send message-summary NOTIFY Event to update phone voicemail status.
+      #
+      # == Parameters
+      #   - uri:      Request URI (sip:alice@wanderland.com:5060)
+      #               To get client URI use *ul_show_contact => contact* function
+      #   - vmaccount:Message Account value. Ex.: sip:*97@asterisk.com
+      #   - new:      Number of new messages. If more than 0 then Messages-Waiting header
+      #               will be "yes". Set to 0 to clear phone MWI
+      #   - old:      (optional) Old messages
+      #   - urg_new:  (optional) New urgent messages
+      #   - urg_old:  (optional) Old urgent messages
+      #
+      def mwi_update uri, vmaccount, new, old = 0, urg_new = 0, urg_old = 0
+        mbody = Hash[
+          'Messages-Waiting'  => (new > 0 ? "yes" : "no"),
+          'Message-Account'   => vmaccount,
+          'Voice-Message'     => "#{new}/#{old} (#{urg_new}/#{urg_old})",
+        ]
+        hf = Hash[
+          'To'                => "<#{uri}>",
+          'From'              => "<#{uri}>;tag=#{SecureRandom.hex}",
+          'Event'             => "message-summary",
+          'Subscription-State'=> "active",
+          'Content-Type'      => "application/simple-message-summary",
+          'Content-Length'    => mbody.map{|k,v| "#{k}: #{v}"}.join("\r\n").length,
+          'nl'                => "",
+        ]
+
+        uac_dlg "NOTIFY", uri, hf.merge(mbody)
+      end
+
+      def set_header(header);"\"#{header}\"";end
+      
+    end
+  end
+end