adhearsion 0.7.5 → 0.7.6

data/apps/default/helpers/manager_proxy.rb

@@ -37,7 +37,24 @@ class PBX
     end
     @@sip_users[:users]
   end
-  def self.record channel, file, format, mix
-
+  
+  def self.originate hash
+    # This is an ugly hack to use until RAI's AMI work is ported in.
+    h = {}
+    h['Application'] = hash.delete :app
+    hash.each { |k,v| h[k.to_s.titleize] = v }
+    @@rami_client.originate h
+  end
+  
+  def self.record hash={}, &block
+    # TODO: Implement me!
+    raise NotImplementedError
+    
+    # defaults = {:file => "#{String.random(5)}", :folder => nil,
+    #             :channel => Thread.current[:VARS]['channel'], :format => 'wav', :mix => '1'}
+    # defaults = defaults.merge hash
+    # PBX.rami_client.... # TODO
   end
+  
+  
 end

data/apps/default/helpers/micromenus.rb

@@ -21,7 +21,7 @@ require 'webrick'
 require 'stringio'
 
 class WEBrick::HTTPRequest
-  def ip() @peeraddr[3] end
+  def ip() @peeraddr[3][/(\d{1,3}\.){3}\d{1,3}/] end
 end
 
 # Micromenu catchers are special hooks that allow integration

data/lib/adhearsion.rb

@@ -1,19 +1,19 @@
 # Adhearsion, open source technology integrator
-# Copyright 2006 Jay Phillips
+# Copyright (C) 2006,2007 Jay Phillips
 # 
-# This program is free software; you can redistribute it and/or
-# modify it under the terms of the GNU General Public License
-# as published by the Free Software Foundation; either version 2
-# of the License, or (at your option) any later version.
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
 # 
-# This program is distributed in the hope that it will be useful,
+# This library is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
 # 
-# You should have received a copy of the GNU General Public License
-# along with this program; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 require 'core_extensions'
 
@@ -69,7 +69,7 @@ module Asterisk
   def input digits=nil, hash={}
     timeout, file = (hash[:timeout] || -1), (hash[:play] || hash[:file] || 'beep')
     result = rawr "GET DATA #{file} #{timeout} #{digits}"
-    result = result[/\=-?\d+/]
+    result = result[/\=-?[\d*]+/]
     result ? result[1..-1] : false
   end
 
@@ -85,20 +85,66 @@ module Asterisk
   end
   alias bill time
 
-  # Requires an AMI connection! Given a block, everything contained
-  # within it will be recorded. If no arguments are given, a String
-  # for the filename will be generated from the current time and a
-  # sequence of random alphanumeric characters.
-  def record hash={}, &block
-    defaults = {:file => "#{String.random(5)}", :folder => nil,
-                :channel => Thread.current[:VARS]['channel'], :format => 'wav', :mix => '1'}
-    defaults = defaults.merge hash
-    #PBX.record
+  # When called, this command will record the current channel to a file. The
+  # recording will stop either when the caller hangs up or when she presses
+  # the # key. Four arguments exist for your use:
+  #
+  # - :file defaults to "/tmp/recording_%d.wav" where %d is a number cleverly
+  #   incremented by Asterisk. If you override this argument, you too can
+  #   use '%d' in the filename to have it automatically incremented for you.
+  #   The return value of record() will be whatever filename Asterisk just used.
+  #   Filenames can be either an absolute path or simple name. When no apparent
+  #   directory is given, Asterisk will use /var/lib/asterisk/sounds. Ensure this
+  #   directory is writable to the user account with which Asterisk runs.
+  #
+  # - :silence specifies the number of seconds Asterisk should wait in silence
+  #   before ending the call. 
+  #
+  # - :max is the maximum length of the sound file in seconds. Feel free to use
+  #   Adhearsion's Fixnum convenience methods here (e.g. 1.minute, 12.hours)
+  #
+  # - :options can be 'skip' to return immediately if the line is not up, or
+  #   'noanswer' to record even if the line is not up.
+  #
+  # === Notes
+  #
+  # Keep in mind if you user decides to hang up to end the recording, the thread
+  # handling the call will end but the file will still be saved. Try to do any
+  # necessary processing before-hand. If you're trying to use the return value
+  # of record(), you may not get it if the thread gets terminated. Instead, create
+  # your own filename and save it somewhere safe (in a database for example) and
+  # then record the user to your pre-created filename.
+  #
+  # === Examples
+  #
+  #   record # A filename will be made for you and returned
+  #   record :file => 'foo.wav'
+  #   record :max => 2.minutes + 30.seconds
+  #   record :file => '/tmp/recordings/COMPLAINT_%d.gsm', :silence => 5
+  #
+  def record hash={}
+    raise NotImplementedError if block_given? # TODO support recording a block of code
+    defaults = {:file => "/tmp/recording_%d.wav", :silence => 0, :max => 0}
+    args = defaults.merge hash
+    
+    exec :Record, args[:file], args[:silence], args[:max], args[:options]
+    args[:file].index('%d') ? get_variable('RECORDED_FILE')[1..-2] : args[:file]
   end
+  
+  # Invokes the AGI RECORD FILE method as outlined below
+  # Note that the timeout value must be expressed in milliseconds
+  def record_file file, hash={}
+		#RECORD FILE <filename> <format> <escape digits> <timeout>
+		format, digits, timeout, beep, silence = (hash[:format] || 'gsm'), (hash[:digits] || '#'), 
+																						 (hash[:timeout] || 15000), (hash[:beep] ? 'BEEP' : nil), ("s=#{hash[:silence]}" || nil)
+		result = rawr "RECORD FILE #{file} #{format} \"#{digits}\" #{timeout} #{beep} #{silence}"
+    result = result[/\=-?\d+/]
+    result ? result[1..-1] : false
+	end
 
   # Waits for single digit numpad key response from the user. If no timeout argument
   # is given, the system will wait indefinitely. The argument is the desired time
-  # to wait fo0r the response in seconds. Feel free to use the ActiveSupport extensions
+  # to wait for the response in seconds. Feel free to use the ActiveSupport extensions
   # for using this method like wait_for_digit(2.minutes) or something similar. When the
   # timeout is encountered (or an error occurs receiving the input), the method
   # returns nil. If the asterisk or pound key was pressed, a String is returned of that
@@ -106,7 +152,7 @@ module Asterisk
   def wait_for_digit timeout=-1
     digit = rawr("WAIT FOR DIGIT #{timeout < 0 ? -1 : timeout / 1000.0}").match(/=(.*)$/)[1].to_i
     return nil if digit <= 0 # If there was an error or timeout
-    return digit.chr if [32,45].include? digit
+    return digit.chr if (32..45).include? digit
     digit - ?0
   end
 
@@ -134,7 +180,7 @@ module Asterisk
   # of syntactically sweet formats:
   #
   #   - A "Group" of users. This is determined by whether the passed group
-  #     responds to the +members+, +users+, +member+, or +user+ methods. If
+  #     responds to the members, users, member, or user methods. If
   #     so, all members of that group will ring simultaneously. This would
   #     be especially useful for, say, technical support groups which all
   #     share the same line. When the first person picks up the line, the
@@ -143,7 +189,7 @@ module Asterisk
   #     standards below.
   #   - An Array of "Users".
   #   - A single "User". A User is defined by something that responds to the
-  #     +extension+ or +extensions+ methods. The return value of these two
+  #     extension or extensions methods. The return value of these two
   #     methods can either be any of the following formats:
   #   - A String. The String can contain a simple number or be a fully
   #     qualified Asterisk-ready String. e.g. 'SIP/codemecca@sipphone'.
@@ -177,19 +223,19 @@ module Asterisk
   # of time (which you likely will to have the call redirect to voicemail for
   # example), then a :for => 15.seconds type of syntax can be used. Examples:
   #
-  #   - dial :jay, :for => 2.minutes
+  #   dial :jay, :for => 2.minutes
   #
   # The result of the last call can be retrieved by using the dial plan
-  # methods +last_call_successful?+, +last_call_unsuccessful?+, or
-  # +last_dial_status+. Note: +last_dial_status+ returns a Symbol representing
+  # methods last_call_successful?, last_call_unsuccessful?, or
+  # last_dial_status. Note: last_dial_status returns a Symbol representing
   # the result of the last call. For more information, see its appropriate
   # documentation.
   # 
   # Additionally, you can use the :options hash key argument to specify options
   # which Asterisk's Dial() application normally takes. For example:
   # 
-  #   - dial :jay, :for => 30.seconds, :options => 'tmw'
-  #   - dial 1_444_555_6666, :options => 'S(30)'
+  #   dial :jay, :for => 30.seconds, :options => 'tmw'
+  #   dial 1_444_555_6666, :options => 'S(30)'
   #
   # == Resources
   #
@@ -322,18 +368,183 @@ module Asterisk
     end
   end
 
+  # == Dialplan Instruction Caching
+  #
+  # If a cynic ever says Ruby doesn't make an efficient dial plan manager,
+  # point them to this little method. The cache() method is given a block
+  # of code and will automagically cache whatever's inside it. The caching
+  # mechanism can even be refined by specifying a time-to-live on the cache
+  # and special variables on which the cache depends.
+  #
+  # Here is a sample block of dial plan code that would be cached indefinitely:
+  #
+  #   play_commands {
+  #     cache do
+  #       File.read('commands.txt').each { |sound_file| play sound_file }
+  #     end
+  #   }
+  # 
+  # This example reads commands.txt, an arbitrary file containing sound file names
+  # on each line and plays them. Because the file access and String
+  # manipulation may be resource intensive, the commands sent to Asterisk
+  # will be cached indefinitely (until Adhearsion restarts in this case), but
+  # the file will be read and parsed only once, improving performance significantly.
+  #
+  # == Caching for a Certain Amount of Time
+  #
+  # Often you may want to cache a block of code, but not indefinitely. A
+  # hash key argument can be given to the cache method to have the stored
+  # code expire after a certain duration.
+  # 
+  #   cache :for => 1.hour do
+  #     play weather_report('Dallas, Texas')
+  #   end
+  #
+  # This example uses the weather helper to pull down information from the internet
+  # and process it. While on a small scale calling this method often would only be
+  # inconvenient to the user waiting for the content, having potentially hundreds
+  # of users calling this method would greatly drag the system down. Caching it for
+  # one hour keeps the system snappy and the users happy.
+  #
+  # == Caching Per a Variable
+  #
+  #   cache :per => extension do
+  #     employee = User.find_by_extension extension
+  #     dial extension
+  #   end
+  # 
+  # Another more creative example:
+  #
+  #   cache :per => extension / 100 do
+  #     # This would be useful if you separated your IVR's endpoints into
+  #     # blocks of 100. For example, say every employee had an extension
+  #     # between 100 and 199. In this case, (extension / 100) would
+  #     # return 1. In this way, any numbers between 100 and 199 would have
+  #     # instructions unique to them cached. Say extension 200 through 299
+  #     # dialed in conference. In this case, instructions pertaining only
+  #     # to conferences would be cached (extension/100 == 2).
+  #   end
+  #
+  # But don't do this:
+  #
+  #   cache :per => extension do
+  #     user = User.find_by_extension extension
+  #     speak "Calling #{user.name}"
+  #     im user.jabber, "Incoming call!"
+  #     dial user
+  #   end
+  #
+  # In this case, the instant message will be sent only once until the cache
+  # expires. This is probably not what you wanted. A working (albeit trivially
+  # simplistic) way to do this would be:
+  # 
+  #   user = User.find_by_extension extension
+  #   cache :per => extension do
+  #     speak "Calling #{user.name}"
+  #   end
+  #   im user.jabber, "Incoming call from #{calleridname}!"
+  #   cache :per => extension do
+  #     dial user
+  #   end
+  #
+  # Yet another cool example:
+  #
+  #   cache :per => Time.now.wday, :for => 1.month do
+  #     # Cache your instructions based on the day of the week, refreshing
+  #     # no more than once a month.
+  #   end
+  #
+  # === Caching Per Multiple Variables
+  # 
+  # If you should wish to cache per several variables, simply encapsulate them in an
+  # Array. For example:
+  # 
+  #   cache :per => [extension, callerid], :for => 1.day+2.hours+30.minutes do
+  #     # Do your crazy crap here
+  #   end
+  #
+  # == Notes on Caching
+  #
+  # - All caches are flushed completely when Adhearsion restarts
+  #
+  # - If a phone call ends before a cache block finishes, nothing will be cached (a good thing).
+  #
+  # - Presently, you cannot nest cache blocks. Doing this will produce bizarre results.
+  #
+  # - Common sense should tell you not to cache per constantly changing things.
+  #   For example, if you're receiving calls from all over the country, don't
+  #   cache per everyone's phone number. This will probably result in an
+  #   OutOfMemoryError as everyone's number will have cached instructions. The
+  #   better way to do this would be to cache the blocks that all numbers share,
+  #   then execute content-specific
+  #
+  # - Variables declared inside of the block won't be accessible outside of the block.
+  #   If you don't want this, declare them outside of the block and use them inside.
+  #
+  # - If you're doing non-dialplan related stuff within a cache, it will only be
+  #   performed once. Don't put your logic to count billing time or something
+  #   similar because that varies between each call. Caching only caches what is
+  #   sent to Asterisk, not your Ruby code (of course).
+  #
+  # - If cached code relies on data from a database, it's best to set its expiration
+  #   to something brief (5 or 10 minutes) because database content is *supposed*
+  #   to change, but the demand of pulling the content out may affect scaling. Having
+  #   the data cached for a short amount of time is happy middle ground.
+  def cache hash={}, &block
+    raise ArgumentError, "Must provide a block to cache!" unless block_given?
+    
+    constraint = hash[:per]
+    ttl = hash[:for]
+    
+    # $cache_dir is a Hash of caller()s. The repository from $cache_dir is
+    # another Hash mapping the :per elements to the cached queue (Array) of
+    # rawr() commands.
+    
+    repo = nil
+    $cache_dir.synchronize do |dir|
+      repo = dir[caller]
+      repo = dir[caller] = {} unless repo
+    end
+    
+    # The first element of each queue is a Time to be used for comparison
+    # with Time.now to determine whether the cache is stale.
+    queue = repo[constraint]
+    queue = nil if queue && queue.first && queue.first < Time.now
+    
+    # If a unexpired queue exists, let's ship its commands off to rawr()
+    if queue then queue[1..-1].each { |cmd| rawr cmd }
+    else
+      # Here, several things may have happened. The call to cache 
+      # could have been executed for the first time, there was no cached
+      # queue for a particular constraint, or the cached expiration's
+      # date has been met.
+      
+      # We cache the commands by setting Thread.current[:cache] which rawr()
+      # will fill with commands it gets. yield then executes the block and
+      # we pull out the commands rawr() gave.
+      Thread.current[:cache] = []
+      yield
+      queue = Thread.current[:cache]
+      queue.unshift ttl ? ttl.from_now : nil
+      $cache_dir.synchronize { repo[constraint] = queue }
+      Thread.current[:cache] = nil
+    end
+  end
+  $cache_dir = {}
+
   # The rawr() method is the main way of receiving a raw response from the Asterisk
   # server. When no argument is given, it will immediately ask for a response,
   # returning that String. When an argument +is+ given, it will first send that
   # command and then return the response that command generated. Everything is
-  # chomp()ed before returned. Pun here totally intended.
+  # chomp()ed before returned.
   def rawr(what=nil)
-    begin
-      putc what if what
-      PBX.io.gets.chomp!
-    rescue => e
-      #log "Socket no longer available for communication. Exceptions will likely occur."
+    if what
+      putc what
+      Thread.current[:cache] << what if Thread.current[:cache]
     end
+    PBX.io.gets.chomp!
+  rescue
+    log "Call likely ended (socket closed). It's okay if exceptions follow."
   end
 
   # Very simply sends the command over the AGI IO socket and forgets about it.
@@ -381,10 +592,10 @@ module Asterisk
 	end
 	
 	# Answer the channel. Adhearsion is configured by default to automatically do this
-	# when a call comes in.
+	# when a call comes in. This behavior can be specified in adhearsion.yml.
 	def answer() rawr 'ANSWER' end
 	# Hangs up the channel. Adhearsion is configured by default to matically do this
-	# when a context completes execution
+	# when a context completes execution. This behavior can be specified in adhearsion.yml.
 	def hangup() rawr 'HANGUP' end
 	# Direct translation of the Asterisk NoOp() application. Used primarily for
 	# viewing debug information in the Asterisk CLI.
@@ -416,14 +627,14 @@ class IAX
   # Simple convenience method to make Adhearsion's DSL more Asterisk-like.
 	# Virtually anything can be provided after the "/", as long as its to_s()
 	# method is what you intended to represent.
-  def self./(arg=nil) IAX(arg) end
+  def self./(arg=nil) "IAX2/#{arg}" end
 end
 
 class ZAP
   # Simple convenience method to make Adhearsion's DSL more Asterisk-like.
 	# Virtually anything can be provided after the "/", as long as its to_s()
 	# method is what you intended to represent.
-  def self./(arg=nil) ZAP(arg) end
+  def self./(arg=nil) "Zap/#{arg}" end
 end
 
 # For users who may try to use the (proper) IAX2 form. See IAX for more info.
@@ -437,6 +648,10 @@ class Zap < ZAP; end
 # this in your own helpers, all methods will need to be class (a.k.a. static) methods
 # since no actual instance of this object is passed around.
 class PBX
+  def method_missing name
+    raise NameError, "Method #{name} not found! Are you sure manager_proxy is configured properly?"
+  end
+  
   def PBX.io() Thread.current[:io] end
 end
 
@@ -476,7 +691,7 @@ class Contexts
     end
     
     def method_missing name, *args, &block
-      Kernel.method_missing name, *args, &block
+      Object::method_missing name, *args, &block
     end
     
     def run_inside &code
@@ -484,9 +699,7 @@ class Contexts
     end
     
     def eval_inside code
-      run_inside do
-        eval code
-      end
+      run_inside { eval code }
     end
   end
 end