ragi 1.0.0

data/call_handler.rb

@@ -0,0 +1,362 @@
+#
+# 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 'uri'
+require 'ragi/call_connection'
+
+module RAGI
+
+  # == Overview
+  # 
+  # This class is the base class for all RAGI call handler objects. To create 
+  # a call handler, derive a class from this class with the suffix "Handler" 
+  # and place it in the file app/handlers/<name>_handler.rb. 
+  #
+  # == Actions
+  #
+  # All public 
+  # methods on the class are by default exposed as actions to the callserver. 
+  # An action can be called by passing a URL like 
+  #
+  #   agi://<server>/<handler>/<action>
+  #
+  # to asterisk. If the action is not specified, then the call server will 
+  # choose one of the two following default actions:
+  #
+  #   dialout - for connections initiated by the call server
+  #   dialup - for connections initiated from outside
+  #
+  # == Helpers
+  #
+  # Helpers are modules that can be loaded as mixins into the call handlers. 
+  # As mixins the implementation of these modules will have access to all the
+  # state of the call handler including the session, params, connection, etc.
+  #
+  # To include a helper, declare it with a line like this in your call handler:
+  #
+  #    helper :FooBar
+  #
+  # The call handler will mixin a module named FooBarHelper, loading the file 
+  # foo_bar_helper.rb if necessary. The standard location for such helper 
+  # files is app/helper.
+  #
+  # == Parameters
+  #
+  # There are a variety of ways that parameters can be passed to a call 
+  # handler. Each of these variables is available through the params hash. 
+  # To retrieve a value from the params hash:
+  #
+  #     @params['Foo']
+  # 
+  # For a call coming in over RAGI you can retrieve AGI session variables. 
+  # These are the variables passed to teh connection when it is established. 
+  # For example, to reference the caller ID:
+  #
+  #     @params[RAGI::CALLERID]
+  #
+  # You can also retrieve query parameters from the AGI URL. For instance, if 
+  # the AGI URL is something like /foo/bar?widget=gizbot, you can retrieve the 
+  # widget value:
+  #
+  #     if @params[:widget] == 'gizbot' then
+  #
+  # If the call was initiated through RAGI::place_call, you can access the
+  # parameters passed to the initiate call. For instance, if you initiate call 
+  # looks like this:
+  #
+  #     RAGI.place_call('2065551212', '/foo/bar',
+  #                             :hash_params => { :param => 123,
+  #                                "foo" => "bar" })
+  #
+  # You can reference these parameters like this:
+  #
+  #     if @params[:param] == 123 && @params["foo"] == "bar" then
+  #
+  # Finally, when you redirect to another handler or process a subhandler, all
+  # the parameters for your call handler are passed along with any additional
+  # parameters you can specify. For instance, this redirect call:
+  #
+  #     redirect(:handler => :foo_bar,
+  #                 :param => 123,
+  #                 "foo" => "bar")
+  #
+  # You can reference these parameters like this:
+  #
+  #     if @params[:param] == 123 && @params["foo"] == "bar" then
+  #  
+  # == Sessions
+  #
+  # A session object is created for each RAGI connection. The session object 
+  # is simply a has object that allows you to store objects in memory during 
+  # the call. Unlike the web, session objects are not maintained across 
+  # connection. You can place objects in the functions using the hash object:
+  #
+  #     @session[:foo] = :bar
+  #
+  # Later you can retrieve the contents using the hash object:
+  #
+  #     if(@session[:foo] == :bar) then
+  #
+  # == Redirection
+  #
+  # A call handler can redirect to another call handler. When you redirect, 
+  # controll of the call is passed to the other call handler when you exit 
+  # your call handler. The session, parameters and connection objects remain 
+  # the same. You can specify handlers & actions for the redirection. If the 
+  # handler is not specified then the existing handler is reused. In addition, 
+  # you can specify additional parameters to be added for the redirected call 
+  # handler.
+  #
+  #     redirect(:handler => :foo,
+  #                 :action => :bar,
+  #                 :param => 123,
+  #                 "foo" => "bar")
+  #
+  # Handlers & actions can be referenced by symbol or string. Handlers can 
+  # also reference an explicit class or a class instance.
+  
+  class CallHandler
+    attr_accessor :connection, :session, :redirect_route
+
+    #-----------------------------------------------------------------------------
+    # PUBLIC INSTANCE METHODS
+    #-----------------------------------------------------------------------------
+
+    # call this method to redirect to another handler. after calling this 
+    # method you should return to the caller. You will not receive 
+    # control of the call back when this handler is complete.
+
+    def redirect(options)
+      @redirect_route = @route.dup.update(options)
+    end
+
+    # call this method to call another handler from within your handler. when 
+    # the other handler has finished control will be returned to the caller.
+
+    def process(options)
+      route = @route.dup.update(options)
+
+      if CallHandler.match_class(self.class, route[:handler]) then
+        RAGI::LOGGER.warn("Warning, creating new instance of handler #{route[:handler]}.")
+      end
+
+      CallHandler.process(route, @connection, self.session)
+    end
+
+    #-----------------------------------------------------------------------------
+    # PUBLIC CLASS METHODS
+    #-----------------------------------------------------------------------------
+
+    # call this method to attach helpers to your call handler. Helpers are 
+    # defined and located in much the same way as helpers on 
+    # ActiveController objects.
+
+    def self.helper(*args)
+      args.flatten.each do |arg|
+        case arg
+        when Module
+          add_template_helper(arg)
+        when String, Symbol
+          file_name  = arg.to_s.underscore + '_helper'
+          class_name = file_name.camelize
+          
+          begin
+            require_dependency("helpers/#{file_name}")
+          rescue LoadError => load_error
+            requiree = / -- (.*?)(\.rb)?$/.match(load_error).to_a[1]
+            msg = (requiree == file_name) ? "Missing helper file helpers/#{file_name}.rb" : "Can't load file: #{requiree}"
+            raise LoadError.new(msg).copy_blame!(load_error)
+          end
+          
+          add_template_helper(class_name.constantize)
+        else
+          raise ArgumentError, 'helper expects String, Symbol, or Module argument'
+        end
+      end
+    end
+
+    # Based on the specified URN, determine the handler & action to use for 
+    # the incoming call.
+
+    def self.route(path)
+      route = {}
+
+      uri = URI.parse(path)
+
+      path = uri.path
+      path = path[1..-1] if path[0] = '/'
+      
+      # todo: deal with paths like foo/bar/1
+      if path.index '/' then
+        route[:handler] = path[0..path.index('/')-1]
+        route[:action] = path[path.index('/')+1..-1]
+      else
+        route[:handler] = path
+        route[:action] = :dialup
+        # todo: check the connection object to see if this is a dialout connection
+      end
+      # todo: extract uri.query into parameters on the route
+      route
+    end
+    
+    # Based on the specified route, load and initialize a handler. we then 
+    # call the appropriate action based on the route. if the handler species 
+    # that we should redirect, then do that.
+
+    def self.process(route, connection, session = {})
+      handler = nil
+
+      while route do
+        
+        # check to see if the handler actually needs to be created
+
+        if !handler ||
+            !match_class(handler.class, route[:handler]) then
+
+          # to create the handler we either create an instance of the 
+          # referenced class or we have to load a dependency and create the 
+          # class referenced.
+
+          case route[:handler]
+          when Class
+            puts "running ragi class"
+            handler = route[:handler].new
+          when String, Symbol
+            puts "running ragi string lookup"
+            file_name  = route[:handler].to_s.underscore + '_handler'
+            puts "filename: #{file_name}"
+            class_name = file_name.camelize
+          
+            begin
+              require_dependency("handlers/#{file_name}")
+            rescue LoadError => load_error
+              requiree = / -- (.*?)(\.rb)?$/.match(load_error).to_a[1]
+              msg = (requiree == file_name) ? "Missing handler file handlers/#{file_name}.rb" : "Can't load file: #{requiree}"
+              raise LoadError.new(msg).copy_blame!(load_error)
+            end
+          
+            handler = class_name.constantize.new
+          else
+            # todo: test support for passing handler as an instance
+            handler = route[:handler]
+          end
+          handler.init_session(route, connection, session)
+        end
+
+        handler.send(route[:action])
+        
+        # if a redirection route was set, then we should loop
+        route = handler.redirect_route
+        handler.redirect_route = nil
+      end
+    end
+
+    #-----------------------------------------------------------------------------
+    # CONNECTION HELPERS
+    #-----------------------------------------------------------------------------
+
+    # We mirror all the methods of the callConnection object
+    def method_missing(meth, *attrs, &block)
+      if @connection.respond_to?(meth)
+        @connection.__send__(meth, *attrs, &block)
+      else
+        super
+      end
+    end
+
+    #-----------------------------------------------------------------------------
+    # INTERNAL METHODS
+    #-----------------------------------------------------------------------------
+    
+    # InitSession is called by the framework to initialize a new call handler 
+    # as it gets constructed. This method should never be called from outside 
+    # the framework.
+
+    def init_session(route, connection, session = {} )
+      @route = route
+      @connection = connection
+      @session = session
+      @redirect_route = nil
+      @call_status = connection.get_call_status
+
+      # Load parameters from the connection
+      @params = connection.params.dup
+      
+      # Extract and add the hash data
+      hashData = connection.get_hash_data
+      if hashData then
+        hashData.each do |name, val|
+          @params[name] = val
+        end
+      end
+      
+      # Add parameters from the route object
+      route.reject { |name, val| [:handler, :action].include? name }.each do |name, val|
+        @params[name] = val
+      end
+    end
+
+    # Add the template module into us
+
+    def self.add_template_helper(mod)
+      self.class_eval "include #{mod}"
+    end
+
+    # Normalizes the class name passed in. For strings and symbols this will 
+    # add the '_handler' string if it is not already present then camelize the 
+    # string ('foo_handler' => 'FooHandler'). For classes this will simply 
+    # ask the class it's name
+
+    def self.normalize_class_name(obj)
+      case obj
+      when Class
+        obj.to_s
+      when String, Symbol
+        obj = obj.to_s
+        if !obj.downcase.include? 'handler' then
+          obj  = obj.to_s.underscore + '_handler'
+        end
+        obj.camelize
+      end
+    end
+
+    # Compare two normalized classes to see if they are the same. The following 
+    # should all return as equivalent:
+    #
+    #   FooBarHelper
+    #   "FooBar"
+    #   :foo_bar
+    #   "foo_bar"
+
+    def self.match_class(a,b)
+      normalize_class_name(a) == normalize_class_name(b)
+    end
+  end
+end

data/call_initiate.rb

@@ -0,0 +1,188 @@
+#
+# 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: callInitiate.rb
+# This class provides a convenient way to place outbound calls through Asterisk.
+# When answered, calls initiated with callInitiate are redirected back to a 
+# RAGI callHandler for processing
+#
+
+require 'cgi'
+require 'yaml'
+
+module RAGI
+  class UsageError < StandardError; end
+  class CmdNotFoundError < StandardError; end
+  class ApplicationError < StandardError; end
+  
+  DEFAULT_CALL_OPTIONS = {
+    :caller_id => "10",
+    :max_retries => 0,
+    :retry_time => 5,
+    :wait_time => 45
+  }
+    
+  class << self
+
+    # The place_call method allows the caller to initiate a call to a given 
+    # phonenumber, handling it with the specified URN. In addition, the caller 
+    # can specify additional parameters:
+    #
+    # :caller_id        - a string containing the caller id to use, e.g. 
+    #                         "8005551212".  There is no name, just a number.
+    #
+    # :hash_params - a hash containing parameters that will be made available 
+    #                         to the call handler
+    #
+    # :call_date        - specify the time the call should occur, specify nil 
+    #                         to make the call occur immediately
+    #
+    # :unique_id       - optional uniqueID useful if you need to delete a 
+    #                         scheduled call later.
+    #
+    # :max_retries   - how many times to retry if the call doesn't go through
+    #
+    # :retry_time     - time to wait between tries in seconds
+    #
+    # :wait_time      - time to wait in seconds for the call to answer, 
+    #                        inclusive of time spent connecting to the PSTN 
+    #                        termination provider.
+    
+    def place_call(phone_number, urn, options = {})
+      options = DEFAULT_CALL_OPTIONS.clone.update(options)
+      
+      options[:agi_server] ||= RAGI::globalConfig["agiServer"]
+
+      RAGI::CallInitiate.place_call(phone_number, 
+                                   options[:caller_id],
+                                   urn,
+                                   options[:hash_params],
+                                   options[:call_date], 
+                                   options[:unique_id],
+                                   options[:max_retries],
+                                   options[:retry_time],
+                                   options[:wait_time],
+                                   options[:set_vars])
+    end
+  end
+
+  class CallInitiate
+
+    # This function is called by RAGI.place_call to actually do the work.
+	def self.place_call(phoneNumber, callerID, urn, hashData, callDate, uniqueID, maxRetries, retryTime, waitTime, extraChannelVars)
+      
+      placeCallNow = false
+      if (callDate == nil)
+        placeCallNow = true
+        callDate = Time.now
+      end
+      
+      if (urn[0..0] != '/') then
+        raise ApplicationError, "Relative URNs cannot be used (found #{urn})"
+      end
+      
+      agiServer = RAGI::globalConfig["agiServer"]
+      RAGI.LOGGER.debug("Initiating call with agi server: #{agiServer}")
+      
+      fileName = getfilename(phoneNumber, callDate, uniqueID)
+      
+      wakeupFile = File.join(RAGI::globalConfig["wakeupCallPath"], fileName.to_s)
+      outgoingFile = File.join(RAGI::globalConfig["outgoingCallPath"], fileName.to_s)
+      callfile = File.new(fileName.to_s, "w+")
+      
+      s = ""
+      s << ";This file was generated by RAGI's callInitiate class\r\n"
+      s << ";File generated date: #{Time.now.strftime('%m-%d-%Y at %H:%M -- %A')}\r\n"
+      s << ";Call date: #{Time.new.strftime('%m-%d-%Y at %H:%M -- %A')}\r\n\r\n"
+      s << "Channel: Local/outbound@dialout\r\n"
+      s << "Callerid: <#{callerID}>\r\n"
+      s << "MaxRetries: #{maxRetries}\r\n"
+      s << "RetryTime: #{retryTime}\r\n"
+      s << "WaitTime: #{waitTime}\r\n"
+      s << "Context: dialout\r\n"
+      s << ";magic extension for outbound calls via RAGI callInitiate\r\n"
+      s << "Extension: outbound-handler\r\n"
+      s << "Priority: 1\r\n"
+      
+      #put in the fundamental call handling variables
+      s << "SetVar: CallInitiate_phonenumber=#{phoneNumber}\r\n"
+      s << "SetVar: CallInitiate_callerid=#{callerID}\r\n"
+      
+      s << "\r\nSetVar: AGI_URL=#{urn}\r\n"
+      s << "\r\nSetVar: AGI_SERVER=#{agiServer}\r\n"
+      
+      if (extraChannelVars)
+        extraChannelVars.each do |name, value| 
+          s << "\r\nSetVar: #{name}=#{value}\r\n"
+        end
+      end
+      
+      marshalData = CGI.escape(YAML.dump(hashData))
+      
+      s << "\r\nSetVar: CallInitiate_hashdata=#{marshalData}\r\n\r\n"
+      
+      callfile.print(s)  
+      
+      #Note:  asterisk call files need these terminating line feeds or else it crashes.
+      callfile.print("\r\n\r\n\r\n")  
+      callfile.close
+      
+      # Setup permissions so that asterisk can read this thing no matter what...
+      File.chmod(0777, fileName)
+      if (placeCallNow == true)
+        FileUtils.mv fileName, outgoingFile #place call now
+        # todo Can't rely on the file still being there.  Asterisk may have grabbed it
+        File.chmod(0777, outgoingFile)	
+      else
+        FileUtils.mv fileName, wakeupFile #schedule call for later
+        File.chmod(0777, wakeupFile)
+      end
+	end
+	
+	def self.delete_call(phoneNumber, callDate, uniqueID)
+      #assert:  callDate is not nil
+      fileName = getfilename(phoneNumber, callDate, uniqueID)
+      wakeupFile = File.join(RAGI::globalConfig["wakeupCallPath"], fileName)
+      FileUtils.rm wakeupFile, :force => true 
+	end
+    
+	# Returns the hashtable representation of str if string is encoded by hashEncode
+	def self.decode_call_params(hashStr)
+      if hashStr then
+        YAML.load(CGI.unescape(hashStr))
+      end
+    end
+    
+    private    
+	def self.getfilename(phoneNumber, callDate, uniqueID)
+      "#{callDate.strftime('%H%M')}.#{phoneNumber}.#{uniqueID}.call"
+	end
+  end
+end