ragi 1.0.0

data/call_server.rb

@@ -0,0 +1,147 @@
+#
+# RAGI - Ruby classes for implementing an AGI server for Asterisk
+# The BSD License for RAGI follows.
+#
+# Copyright (c) 2005, SNAPVINE LLC (www.snapvine.com)
+# All rights reserved.
+
+# Redistribution and use in source and binary forms, with or without 
+# modification, are permitted provided that the following conditions are met:
+#
+#    * Redistributions of source code must retain the above copyright notice, 
+#       this list of conditions and the following disclaimer.
+#    * 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.
+#    * Neither the name of SNAPVINE nor the names of its 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 HOLDERS AND CONTRIBUTORS "AS IS" 
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE 
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
+# DAMAGES (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.
+
+require 'webrick/config'
+require 'webrick/log'
+require 'webrick/server'
+require 'ragi/call_handler'
+require 'ragi/call_connection'
+require 'ragi/config'
+require 'thread'
+
+module RAGI
+  VERSION = "0.0.1"
+
+  @globalConfig = nil
+
+  def self.LOGGER
+    @logger ||= WEBrick::Log::new
+    @logger
+  end
+
+  def self.LOGGER=(logger)
+    @logger = logger
+  end
+
+  def self.globalConfig
+    # This assignment will make a dup
+    @globalConfig ||= RAGI::Config::Globals
+    @globalConfig
+  end
+
+  def self.globalConfig=(newConfig)
+    @globalConfig = newConfig.dup()
+  end
+  
+  class CallServer
+    @incomingcallsocket = nil
+
+    # 4573 = asterisk AGI
+    # RAGI::CallHandler - default handler
+    
+    def initialize(config = {}, default = RAGI::Config::Standard)
+      @config = default.dup.update(config)
+      @config[:Logger] ||= WEBrick::Log::new
+      @config[:ParentStopCallback] = @config[:StopCallback] if @config[:StopCallback]
+      @config[:StopCallback] = method('shutdown_done')
+
+      RAGI.LOGGER = @config[:Logger]
+
+      @mutex = Mutex.new
+      @signal = ConditionVariable.new
+      @running = true
+
+      if (@incomingcallsocket == nil)
+        begin
+          # code to executed in a thread
+          RAGI.LOGGER.info("#{self.class.name}: default-handler=#{@config[:DefaultHandler].to_s} port=#{@config[:Port]}")
+          @incomingcallsocket = WEBrick::GenericServer.new( @config )  
+          
+          @incomingcallsocket.start{ |sock|
+            cc = CallConnection.new(sock)
+            
+            route = {
+              :handler => @config[:DefaultHandler],
+              :action => :dialup
+            }
+            
+            # the default call handler comes from config environment.rb
+            
+            if (cc.agi_url != nil && cc.agi_url != '/')  
+              route = CallHandler.route(cc.agi_url)
+            end
+            RAGI.LOGGER.info("#{self.class.name}: processing call with #{route[:handler].to_s}")
+            
+            CallHandler.process(route, cc)
+
+            # todo: Catch exceptions and say something to the user
+            # before we disconnect them.  Something like this maybe:
+            #
+            # rescue StandardError => err
+            #  if (cc) then
+            #   cc.play_sound('tc/std/sorry-error')
+            #   cc.hang_up()
+            #  end
+            #  raise
+            # end
+          }
+          RAGI.LOGGER.info("#{self.class.name}: server shutdown port=#{@config[:Port]}")
+          
+        rescue StandardError => err
+          RAGI.LOGGER.error("#{err.message}")
+          RAGI.LOGGER.error(err.backtrace.join("\n"))
+        end
+        
+      end
+    end    
+
+    def shutdown
+      @incomingcallsocket.shutdown
+    end
+
+    def shutdown_done
+      RAGI.LOGGER.debug("#{self.class.name}: Shutdown complete")
+
+      @config[:ParentStopCallback].call if @config[:ParentStopCallback]
+      @mutex.synchronize do
+        @running = false
+        @signal.signal
+      end
+    end
+    
+    def join
+      @mutex.synchronize do
+        if @running
+          @signal.wait(@mutex)
+        end
+      end      
+    end      
+  end
+end

data/config.rb

@@ -0,0 +1,68 @@
+#
+# RAGI - Ruby classes for implementing an AGI server for Asterisk
+# The BSD License for RAGI follows.
+#
+# Copyright (c) 2005, SNAPVINE LLC (www.snapvine.com)
+# All rights reserved.
+
+# Redistribution and use in source and binary forms, with or without 
+# modification, are permitted provided that the following conditions are met:
+#
+#    * Redistributions of source code must retain the above copyright notice, 
+#       this list of conditions and the following disclaimer.
+#    * 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.
+#    * Neither the name of SNAPVINE nor the names of its 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 HOLDERS AND CONTRIBUTORS "AS IS" 
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE 
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
+# DAMAGES (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.
+#
+# config.rb -- Default configurations.
+#
+
+require 'webrick/config'
+require 'ragi/call_handler'
+
+module RAGI
+  
+  DEFAULT_PORT = 4573
+
+  module Config
+
+    # for HTTPServer, HTTPRequest, HTTPResponse ...
+    Standard = WEBrick::Config::General.dup.update(
+      :Port           => RAGI::DEFAULT_PORT,
+      :HandlerMap     => {}
+    )
+
+    Globals = {
+      # Name of the box running the agi server, so that asterisk can find it
+      # by default this will use your Ruby server's name
+      "agiServer" => `hostname`.strip(),
+      
+      # Path to use for saving outgoing call files
+      "outgoingCallPath" => 
+        ENV['RAGI_OUT_CALL_PATH'] ? ENV['RAGI_OUT_CALL_PATH'] : "var/spool/asterisk/outgoing",
+
+      # Path to use for saving wakeup call files
+      "wakeupCallPath" =>
+        ENV['RAGI_WAKEUP_CALL_PATH'] ? ENV['RAGI_WAKEUP_CALL_PATH'] : "var/spool/asterisk/wakeups",
+
+      # Path to the built-in sound files relative to the SIP server.
+      "sipSoundPath" => 
+        ENV['RAGI_SIP_SOUND_PATH'] ? ENV['RAGI_SIP_SOUND_PATH'] : "var/lib/asterisk/sounds"
+    }
+
+  end
+end

data/ragi.gempsec

@@ -0,0 +1,23 @@
+require "rubygems"
+require "rake"
+
+spec = Gem::Specification.new do |gem|
+   gem.name        = "ragi"
+   gem.version     = "1.0.0"
+   gem.author      = "Joe Heitzeberg"
+   gem.email       = "joe_AT_snapvine.com"
+   gem.homepage    = "http://rubyforge.org/projects/ragi"
+   gem.platform    = Gem::Platform::RUBY
+   gem.summary     = "RAGI allows you to create useful telephony applications using Asterisk and Ruby [on Rails]."
+   gem.description = "RAGI allows you to create useful telephony applications using Asterisk and Ruby [on Rails].  Please see the included README file for more information"
+   gem.has_rdoc    = false
+
+   gem.files = FileList['example-call-audio.mp3', 'ragi.gempsec', 'CHANGELOG', 'README', '*.rb', 'RAGI Overview_files/*', 'sample-apps/simon/*.rb', 'sample-apps/simon/sounds/README', 'sample-apps/simon/sounds/*.gsm'].to_a
+   gem.files.reject! { |fn| fn.include? "SVN" }
+end
+
+if $0 == __FILE__
+   Gem.manage_gems
+   Gem::Builder.new(spec).build
+end
+

data/sample-apps/simon/simon_handler.rb

@@ -0,0 +1,94 @@
+#  RAGI -- Ruby Asterisk Gateway Interface
+#  See ragi.sourceforge.net for more information.
+#  Sponsored by SnapVine, Inc (www.snapvine.com)
+#
+#  Class:  SimonHandler
+#  Description:  this call handler implements a simple memory game over the phone.
+#
+
+require 'ragi/call_handler'
+
+class SimonHandler < RAGI::CallHandler
+  APP_NAME = 'simon'
+    
+    # When the RAGI server connects from Asterisk over AGI to our app, it calls this method.	
+    def dialup
+      answer  # answer the call
+      wait(1)  # give it 1 seconds to make sure the connection is established
+      
+      
+      playAgain = true
+      while (playAgain)
+        instructions               # tell the caller how to play the game
+        score = play_game           # start the game and play it, returning the score when done
+        announce_score(score)         # tell them how they did
+        playAgain = ask_play_again   # ask if they want to play again
+      end
+      say_goodbye
+      hang_up  #end the call
+    end
+    
+    def instructions
+      play_sound("simon-welcome")
+    end
+    
+    def play_game  
+      
+      intArray = [rand(10)]
+      score = 0
+      
+      # test the user's memory on the current int array
+      while memory_test(intArray)
+        score += 1
+        
+        # grow the array by one digit   
+        intArray << rand(10) # choose a number between 0 and 9 inclusive
+        
+        wait(1)
+      end
+
+      score
+    end
+    
+    def memory_test(intArray)
+      # say each number in the array
+      intArray.each do |number|
+        play_sound("simon-#{number}")  # there are sounds like simon-6.gsm
+      end
+      
+      # listen for user key presses (number of presses should be == intArray.length)
+      # Note:  give about 1 second per key press (intArray.length * 1500)
+      resultStr = get_data("simon-beep", (intArray.length * 1500), intArray.length)
+      
+      # Check if what they entered matches the int array
+      if (resultStr == intArray.join(""))  # note:  join converts from array to string
+        return true   
+      else
+        play_sound("simon-gameover") 
+        return false
+      end  
+    end
+    
+    def announce_score(score)
+      if (score <= 9)
+        play_sound("simon-score")
+        play_sound("simon-#{score.to_s}")
+      end
+      if (score < 5)
+        play_sound("simon-low")
+      elsif (score < 10)
+        play_sound("simon-medium")
+      else
+        play_sound("simon-high")
+      end
+    end
+    
+    def ask_play_again
+      # Give the user three seconds to press a digit
+      return (get_data("simon-again", 3000, 1).length > 0)
+    end
+    
+    def say_goodbye
+      play_sound("simon-goodbye")
+    end
+  end

data/sample-apps/simon/sounds/README

@@ -0,0 +1,9 @@
+These are the sounds needed for the simon sample app.
+
+You'll need to copy these sounds directly to the default sounds directory on your Asterisk server (e.g. var/lib/asterisk/sounds/) in order to use the simon game app.
+
+In the simon call handler, it plays these sounds using the playSound command, e.g.:
+play_sound("simon-welcome")
+
+This command tells the asterisk server to play the sound "simon-welcome.gsm" from the asterisk server's default sound location (e.g. var/lib/asterisk/sounds/simon-welcome.gsm)
+

data/start_ragi.rb

@@ -0,0 +1,41 @@
+#
+# RAGI - Ruby classes for implementing an AGI server for Asterisk
+# The BSD License for RAGI follows.
+#
+# Copyright (c) 2005, SNAPVINE LLC (www.snapvine.com)
+# All rights reserved.
+
+# Redistribution and use in source and binary forms, with or without 
+# modification, are permitted provided that the following conditions are met:
+#
+#    * Redistributions of source code must retain the above copyright notice, 
+#       this list of conditions and the following disclaimer.
+#    * 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.
+#    * Neither the name of SNAPVINE nor the names of its 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 HOLDERS AND CONTRIBUTORS "AS IS" 
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE 
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
+# DAMAGES (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.
+#
+# Class: start_ragi.rb
+# This class provides a server to answer incoming AGI requests from Asterisk.
+# It is configured to run the sample app, Simon.
+#
+
+
+require 'ragi/call_server'
+require 'ragi/sample-apps/simon/simon_handler'
+
+RAGI::CallServer.new( :DefaultHandler => SimonHandler )
+

data/test.rb

@@ -0,0 +1,109 @@
+#
+# RAGI - Ruby classes for implementing an AGI server for Asterisk
+# The BSD License for RAGI follows.
+#
+# Copyright (c) 2005, SNAPVINE LLC (www.snapvine.com)
+# All rights reserved.
+
+# Redistribution and use in source and binary forms, with or without 
+# modification, are permitted provided that the following conditions are met:
+#
+#    * Redistributions of source code must retain the above copyright notice, 
+#       this list of conditions and the following disclaimer.
+#    * 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.
+#    * Neither the name of SNAPVINE nor the names of its 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 HOLDERS AND CONTRIBUTORS "AS IS" 
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE 
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
+# DAMAGES (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 RAGI
+  # This class is useful for writing unit tests
+  class TestSocket
+    
+    def initialize(params, messages)
+      @params = params
+      @messages = messages
+      @inParams = true
+      @currentIndex = 0
+    end
+
+    def self.Exec(cmd, params)
+      [ "EXEC #{cmd} #{params}", "200 result=0"]
+    end
+
+    def self.GetData(soundfile, result)
+      ["GET DATA #{soundfile} 2000", "200 result=#{result} (timeout)"]
+    end
+
+    def self.StreamFile(soundfile, escapeDigits, initialOffset, result, endpos)
+      ["STREAM FILE #{soundfile} \"#{escapeDigits}\" #{initialOffset}", 
+        "200 result=#{result} endpos=#{endpos}"]
+    end
+
+    def self.PlaySound(soundfile)
+      [ "EXEC playback #{soundfile}", "200 result=0"]
+    end
+
+    def self.SayNumber(number)
+      SayNumberFull(number, " \"*#\"")
+    end
+
+    def self.SayNumberFull(number, escapeDigits)
+      [ "SAY NUMBER #{number} \"#{escapeDigits}\"", "200 result=0"]
+    end
+
+    def self.HangUp()
+      [ "HANGUP", "200 result=0"]
+    end
+
+    def print(msg)
+      if @inParams
+        raise StandardError, "Should not receive commands until parameters are parse"
+      end
+
+      if (!@messages[@currentIndex])
+        raise StandardError, "Too many messages received\nMessage =#{msg}= received"
+      end
+
+      if (msg != @messages[@currentIndex][0])
+        raise StandardError, "Unexpected message received\nMessage =#{msg}= received\nExpected =#{@messages[@currentIndex][0]}"
+      end
+    end
+
+    def gets
+      if (@inParams) then
+        if (@currentIndex < @params.length) then
+          key = @params.keys[@currentIndex]
+          val =  "#{key}: #{@params[@params.keys[@currentIndex]]}"
+          @currentIndex += 1
+        else
+          @currentIndex = 0
+          @inParams = false
+          val = ''
+        end
+      else
+        if (@currentIndex < @messages.length) then
+          val = @messages[@currentIndex][1]
+          @currentIndex += 1
+        else
+          raise StandardError, "Unexpected messages past end of test case"
+          @currentIndex = 0
+          val = '\n'
+        end
+      end
+      val
+    end
+  end
+end