eric-adhearsion 0.7.999 → 0.8.0

data/lib/adhearsion/initializer/configuration.rb

@@ -24,8 +24,11 @@ module Adhearsion
     
     class << self
       def configure(&block)
-        Adhearsion.module_eval { remove_const(:AHN_CONFIG) } if Adhearsion.const_defined?(:AHN_CONFIG)
-        Adhearsion.const_set(:AHN_CONFIG, new(&block))
+        if Adhearsion.const_defined?(:AHN_CONFIG)
+          yield AHN_CONFIG if block_given?
+        else
+          Adhearsion.const_set(:AHN_CONFIG, new(&block))
+        end
       end
     end
     
@@ -33,10 +36,6 @@ module Adhearsion
     attr_accessor :end_call_on_hangup
     attr_accessor :end_call_on_error
     
-    def logging(options)
-      Adhearsion::Logging.logging_level = options[:level]
-    end
-    
     def initialize
       @automatically_answer_incoming_calls = true
       @end_call_on_hangup                  = true
@@ -44,6 +43,59 @@ module Adhearsion
       yield self if block_given?
     end
     
+    def ahnrc
+      @ahnrc
+    end
+    
+    ##
+    # Load the contents of an .ahnrc file into this Configuration.
+    #
+    # @param [String, Hash] ahnrc String of YAML .ahnrc data or a Hash of the pre-loaded YAML data structure
+    #
+    def ahnrc=(new_ahnrc)
+      case new_ahnrc
+        when Hash
+          @raw_ahnrc = new_ahnrc.to_yaml.freeze
+          @ahnrc = new_ahnrc.clone.freeze
+        when String
+          @raw_ahnrc = new_ahnrc.clone.freeze
+          @ahnrc = YAML.load(new_ahnrc).freeze
+      end
+    end
+    
+    def logging(options)
+      Adhearsion::Logging.logging_level = options[:level]
+    end
+    
+    ##
+    # Adhearsion's .ahnrc file is used to define paths to certain parts of the framework. For example, the name dialplan.rb
+    # is actually specified in .ahnrc. This file can actually be just a filename, a filename with a glob (.e.g "*.rb"), an
+    # Array of filenames or even an Array of globs.
+    #
+    # @param [String,Array] String segments which convey the nesting of Hash keys through .ahnrc
+    # @raise [RuntimeError] If ahnrc has not been set yet with #ahnrc=()
+    # @raise [NameError] If the path through the ahnrc is invalid
+    #
+    def files_from_setting(*path_through_config)
+      raise RuntimeError, "No ahnrc has been set yet!" unless @ahnrc
+      queried_nested_setting = path_through_config.flatten.inject(@ahnrc) do |hash,key_name|
+        if hash.kind_of?(Hash) && hash.has_key?(key_name)
+          hash[key_name]
+        else
+          raise NameError, "Paths #{path_through_config.inspect} not found in .ahnrc!"
+        end
+      end
+      raise NameError, "Paths #{path_through_config.inspect} not found in .ahnrc!" unless queried_nested_setting
+      queried_nested_setting = Array queried_nested_setting
+      queried_nested_setting.map { |filename| files_from_glob(filename) }.flatten.uniq
+    end
+    
+    private
+    
+    def files_from_glob(glob)
+      Dir.glob "#{AHN_ROOT}/#{glob}"
+    end
+    
     class AbstractConfiguration
       extend ConfigurationEntryPoint
       

data/lib/adhearsion/initializer/database.rb

@@ -23,7 +23,7 @@ module Adhearsion
         private
 
         def create_call_hook_for_connection_cleanup
-          Hooks::BeforeCall.create_hook do
+          Events.register_callback([:asterisk, :before_call]) do
             ActiveRecord::Base.verify_active_connections!
           end
         end
@@ -33,7 +33,7 @@ module Adhearsion
         end
 
         def require_models
-          all_models.each do |model|
+          AHN_CONFIG.files_from_setting("paths", "models").each do |model|
             load model
           end
         end
@@ -46,47 +46,4 @@ module Adhearsion
     end
     
   end
-end
-
-=begin
-db_config = Adhearsion::Configuration.core.database
-if db_config
-  unless Adhearsion::Paths.manager_for? "models"
-    raise "No paths specified for the database 'models' in .ahnrc! Aborting."
-  end
-  require 'active_record'
-  
-  ActiveRecord::Base.verification_timeout = 14400
-  ActiveRecord::Base.logger = Logger.new("log/database.log")
-  ActiveRecord::Base.establish_connection db_config
-  
-  all_models.each { |model| require model }
-  
-  # Below is a monkey patch for keeping ActiveRecord connections alive.
-  # http://www.sparecycles.org/2007/7/2/saying-goodbye-to-lost-connections-in-rails
-  
-  module ActiveRecord
-    module ConnectionAdapters
-      class MysqlAdapter
-        def execute(sql, name = nil) #:nodoc:
-          reconnect_lost_connections = true
-          begin
-            log(sql, name) { @connection.query(sql) }
-          rescue ActiveRecord::StatementInvalid => exception
-            if reconnect_lost_connections and exception.message =~ /(Lost connection to MySQL server during query|MySQL server has gone away)/
-              reconnect_lost_connections = false
-              reconnect!
-              retry
-            elsif exception.message.split(":").first =~ /Packets out of order/
-              raise ActiveRecord::StatementInvalid, "'Packets out of order' error was received from the database. Please update your mysql bindings (gem install mysql) and read http://dev.mysql.com/doc/mysql/en/password-hashing.html for more information.  If you're on Windows, use the Instant Rails installer to get the updated mysql bindings." 
-            else
-              raise
-            end
-          end
-        end
-      end
-    end
-  end
-  
-end
-=end
+end

data/lib/adhearsion/initializer/drb.rb

@@ -8,17 +8,23 @@ module Adhearsion
     class DrbInitializer
 
       class << self
-
+        
         def start
           config = Adhearsion::AHN_CONFIG.drb
           DRb.install_acl ACL.new(config.acl) if config.acl
-          DRb.start_service "druby://#{config.host}:#{config.port}", Adhearsion::DrbDoor.instance
+          
+          drb_door = Object.new
+          Components.component_manager.extend_object_with(drb_door, :rpc)
+          
+          DRb.start_service "druby://#{config.host}:#{config.port}", drb_door
+          
           ahn_log "Starting DRb on #{config.host}:#{config.port}"
         end
-  
+        
         def stop
           DRb.stop_service
         end
+        
       end
     end
   end

data/lib/adhearsion/initializer/freeswitch.rb

@@ -15,8 +15,8 @@ if oes_enabled
 
   server = Adhearsion::VoIP::FreeSwitch::OesServer.new port, host
 
-  Adhearsion::Hooks::AfterInitialized.create_hook { server.start }
-  Adhearsion::Hooks::ThreadsJoinedAfterInitialized.create_hook { server.join }
-  Adhearsion::Hooks::TearDown.create_hook { server.stop }
+  Events.register_callback(:after_initialized) { server.start }
+  Events.register_callback(:shutdown) { server.stop }
+  IMPORTANT_THREADS << server
 
 end

data/lib/adhearsion/initializer/rails.rb

@@ -18,7 +18,7 @@ module Adhearsion
           load_rails
           if defined? ActiveRecord
             ActiveRecord::Base.allow_concurrency = true
-            Hooks::BeforeCall.create_hook do
+            Events.register_callback([:asterisk, :before_call]) do
               ActiveRecord::Base.verify_active_connections!
             end
           end

data/lib/adhearsion/tasks.rb

@@ -4,6 +4,7 @@ require 'adhearsion/tasks/database'
 require 'adhearsion/tasks/testing'
 require 'adhearsion/tasks/generating'
 require 'adhearsion/tasks/lint'
+require 'adhearsion/tasks/deprecations'
 
 namespace :adhearsion do
   desc "Dump useful information about this application's adhearsion environment"
@@ -12,4 +13,4 @@ namespace :adhearsion do
   end
 end
 
-task :default => "adhearsion:about"
+task :default => "adhearsion:about"

data/lib/adhearsion/tasks/deprecations.rb

@@ -0,0 +1,59 @@
+namespace :deprecations do
+  desc <<-DESC
+Older versions of Adhearsion had an .ahnrc "paths" section similar to the following...
+
+  paths:
+    models:
+      directory: models
+      pattern: *.rb
+
+This has been deprecated. The new format is this:
+
+  paths:
+    models: {models,gui/app/models}/*.rb
+
+This Rake task will fix your .ahnrc if you have 
+  DESC
+  task :fix_ahnrc_path_format do
+    puts "\nThis will remove all comments from your .ahnrc file. A backup will be created as .ahnrc.backup."
+    puts "If you wish to do this manually to preserve your comments, simply overwrite .ahnrc with .ahnrc.backup"
+    puts "and apply the change manually."
+    puts 
+    
+    require 'fileutils'
+    require 'yaml'
+    
+    ahnrc_file = File.expand_path(".ahnrc")
+    
+    FileUtils.cp ahnrc_file, ahnrc_file + ".backup"
+    ahnrc_contents = YAML.load_file ahnrc_file
+    
+    abort '.ahnrc does not have a "paths" section!' unless ahnrc_contents.has_key? "paths"
+    
+    paths = ahnrc_contents["paths"]
+    paths.clone.each_pair do |key,value|
+      if value.kind_of?(Hash)
+        if value.has_key?("directory") || value.has_key?("pattern")
+          directory, pattern = value.values_at "directory", "pattern"
+          new_path = "#{directory}/#{pattern}"
+          
+          puts "!!! CHANGING KEY #{key.inspect}!"
+          puts "!!! NEW: #{new_path.inspect}"
+          puts "!!! OLD:\n#{{key => value}.to_yaml.sub("---", "")}\n\n"
+          
+          paths[key] = new_path
+        end
+      end
+    end
+    
+    ahnrc_contents["paths"] = paths
+    new_yaml = ahnrc_contents.to_yaml.gsub("--- \n", "")
+    
+    puts "New .ahnrc file:\n" + ("#" * 25) + "\n"
+    puts new_yaml
+    puts '#' * 25
+    
+    File.open(ahnrc_file, "w") { |file| file.puts new_yaml }
+    puts "Wrote to .ahnrc. Done!"
+  end
+end

data/lib/adhearsion/version.rb

@@ -1,8 +1,8 @@
 module Adhearsion #:nodoc:
   module VERSION #:nodoc:
-    MAJOR = 0   unless defined? MAJOR
-    MINOR = 7   unless defined? MINOR
-    TINY  = 999 unless defined? TINY
+    MAJOR = 0 unless defined? MAJOR
+    MINOR = 8 unless defined? MINOR
+    TINY  = 0 unless defined? TINY
 
     STRING = [MAJOR, MINOR, TINY].join('.') unless defined? STRING
   end

data/lib/adhearsion/voip/asterisk.rb

@@ -1,4 +1,4 @@
 require File.dirname(__FILE__) + "/dsl/numerical_string"
 require File.dirname(__FILE__) + "/asterisk/agi_server"
-require File.dirname(__FILE__) + "/asterisk/ami"
-require File.dirname(__FILE__) + "/asterisk/commands"
+require File.dirname(__FILE__) + "/asterisk/manager_interface"
+require File.dirname(__FILE__) + "/asterisk/commands"

data/lib/adhearsion/voip/asterisk/agi_server.rb

@@ -12,8 +12,8 @@ module Adhearsion
             end
             
             def serve(io)
-              Hooks::BeforeCall.trigger_hooks
-          	  call = Adhearsion.receive_call_from(io)
+              call = Adhearsion.receive_call_from(io)
+              Events.trigger_immediately([:asterisk, :before_call], call)
           	  ahn_log.agi "Handling call with variables #{call.variables.inspect}"
           	  
           	  return DialPlan::ConfirmationManager.handle(call) if DialPlan::ConfirmationManager.confirmation_call?(call)
@@ -26,16 +26,16 @@ module Adhearsion
               call.hangup!
             rescue FailedExtensionCallException => failed_call
               begin
-                ahn_log.agi "Received \"failed\" meta-call with :failed_reason => #{failed_call.call.failed_reason.inspect}. Executing OnFailedCall hooks."
-                Hooks::OnFailedCall.trigger_hooks(failed_call.call)
+                ahn_log.agi "Received \"failed\" meta-call with :failed_reason => #{failed_call.call.failed_reason.inspect}. Executing Executing /asterisk/failed_call event callbacks."
+                Events.trigger [:asterisk, :failed_call], failed_call.call
                 call.hangup!
               rescue => e
                 ahn_log.agi.error e
               end
             rescue HungupExtensionCallException => hungup_call
               begin
-                ahn_log.agi "Received \"h\" meta-call. Executing OnHungupCall hooks."
-                Hooks::OnHungupCall.trigger_hooks(hungup_call.call)
+                ahn_log.agi "Received \"h\" meta-call. Executing /asterisk/call_hangup event callbacks."
+                Events.trigger [:asterisk, :call_hangup], hungup_call.call
                 call.hangup!
               rescue => e
                 ahn_log.agi.error e
@@ -47,7 +47,10 @@ module Adhearsion
             rescue => e
               ahn_log.agi.error e.inspect
               ahn_log.agi.error e.backtrace.map { |s| " " * 5 + s }.join("\n")
+            ensure
+              Adhearsion.remove_inactive_call call rescue nil
             end
+            
           end
          
           DEFAULT_OPTIONS = { :server_class => RubyServer, :port => 4573, :host => "0.0.0.0" } unless defined? DEFAULT_OPTIONS

data/lib/adhearsion/voip/asterisk/commands.rb

@@ -7,6 +7,22 @@ module Adhearsion
       module Commands
         
         RESPONSE_PREFIX = "200 result=" unless defined? RESPONSE_PREFIX
+        
+        # These are the status messages that asterisk will issue after a dial command is executed.
+        # More information here: http://www.voip-info.org/wiki/index.php?page=Asterisk+variable+DIALSTATUS
+        # Here is a current list of dial status messages which are not all necessarily supported by adhearsion:
+        # 
+        # ANSWER: Call is answered. A successful dial. The caller reached the callee.
+        # BUSY: Busy signal. The dial command reached its number but the number is busy.
+        # NOANSWER: No answer. The dial command reached its number, the number rang for too long, then the dial timed out.
+        # CANCEL: Call is cancelled. The dial command reached its number but the caller hung up before the callee picked up.
+        # CONGESTION: Congestion. This status is usually a sign that the dialled number is not recognised.
+        # CHANUNAVAIL: Channel unavailable. On SIP, peer may not be registered.
+        # DONTCALL: Privacy mode, callee rejected the call
+        # TORTURE: Privacy mode, callee chose to send caller to torture menu
+        # INVALIDARGS: Error parsing Dial command arguments (added for Asterisk 1.4.1, SVN r53135-53136)
+        #
+        #
         DIAL_STATUSES   = Hash.new(:unknown).merge(:answer      => :answered,
                                                    :congestion  => :congested, 
                                                    :busy        => :busy,
@@ -36,17 +52,47 @@ module Adhearsion
           end
         end
         
+        # This method is the underlying method executed by nearly all the command methods in this module.
+        # It is used to send the plaintext commands in the proper AGI format over TCP/IP back to an Asterisk server via the
+        # FAGI protocol.
+        # It is not recommended that you call this method directly unless you plan to write a new command method
+        # in which case use this method you to communicate directly with an Asterisk server via the FAGI protocol.
+        # For more information about FAGI visit: http://www.voip-info.org/wiki/view/Asterisk+FastAGI
         def raw_response(message = nil)
           ahn_log.agi.debug ">>> #{message}"
           write message if message
           read
         end
         
+        # The answer command must be called first before any other commands can be issued.
+        # In typical adhearsion applications the answer command is called by default as soon
+        # as a call is transfered to a valid context in dialplan.rb.
+        # If you do not want your adhearsion application to automatically issue an answer command,
+        # then you must edit your startup.rb file and configure this setting.
+        # Keep in mind that you should not need to issue another answer command after 
+        # an answer command has already been issued either explicitly by your code or implicitly
+        # by the standard adhearsion configuration.
         def answer
           raw_response "ANSWER"
           true
         end
         
+        # This asterisk dialplan command allows you to instruct Asterisk to start applications
+        # which are typically run from extensions.conf.  For a complete list of these commands
+        # please visit: http://www.voip-info.org/wiki/view/Asterisk+-+documentation+of+application+commands
+        #
+        # The most common commands are already made available through the FAGI interface provided
+        # by this code base.  For commands that do not fall into this category, then exec is what you
+        # should use.
+        #
+        # For example, if there are specific asterisk modules you have loaded that will not 
+        # available through the standard commands provided through FAGI - then you can used EXEC.
+        #
+        # Example:
+        # execute 'SIPAddHeader', '"Call-Info: answer-after=0"
+        # 
+        # Using execute in this way will add a header to an existing SIP call.
+        # 
         def execute(application, *arguments)
           result = raw_response("EXEC #{application} #{arguments * '|'}")
           return false if error?(result)
@@ -54,6 +100,10 @@ module Adhearsion
         end
         
         # Hangs up the current channel.
+        # After this command is issued, your application will stop executing.
+        # This should be used in the same way you would call the ruby exit() method to exit an application.
+        # If it is necessary to do some additional cleanup tasks before returning control back to asterisk, then
+        # make sure you have setup a begin...ensure block in the context of your adhearsion application dialplan.
         def hangup
           raw_response 'HANGUP'
         end
@@ -113,9 +163,15 @@ module Adhearsion
       	
       	def with_next_message(&block)
       	  raise LocalJumpError, "Must supply a block" unless block_given?
-      	  block.call @call.inbox.pop
+      	  block.call(next_message)
     	  end
 
+        # This command shouled be used to advance to the next message in the Asterisk Comedian Voicemail application
+        def next_message
+          @call.inbox.pop
+        end
+
+        # This command should be used to check if a message is waiting on the Asterisk Comedian Voicemail application.
         def messages_waiting?
           not @call.inbox.empty?
         end
@@ -478,6 +534,10 @@ module Adhearsion
           execute "MeetMe", conference_id, command_flags, options[:pin]
         end
         
+        # Issue this command to access a channel variable that exists in the asterisk dialplan (i.e. extensions.conf)
+        # A complete description is available here: http://www.voip-info.org/wiki/view/get+variable
+        # Use get_variable to pass information from other modules or high level configurations from the asterisk dialplan
+        # to the adhearsion dialplan.
       	def get_variable(variable_name)
       	  result = raw_response("GET VARIABLE #{variable_name}")
       	  case result
@@ -488,6 +548,12 @@ module Adhearsion
     	    end
     	  end
     	  
+    	  # Use set_variable to pass information back to the asterisk dial plan.
+    	  # A complete decription is available here: http://www.voip-info.org/wiki/view/set+variable
+    	  # Keep in mind that the variables are not global variables.  These variables only exist for the channel
+    	  # related to the call that is being serviced by the particular instance of your adhearsion application.
+    	  # You will not be able to pass information back to the asterisk dialplan for other instances of your adhearsion
+    	  # application to share.  Once the channel is "hungup" then the variables are cleared and their information is gone.
     	  def set_variable(variable_name, value)
     	    raw_response("SET VARIABLE %s %p" % [variable_name.to_s, value.to_s]) == "200 result=1"
   	    end
@@ -576,6 +642,42 @@ module Adhearsion
           voicemail_main
         end
         
+        # Use this command to dial an extension i.e. "phone number" in asterisk
+        # This command maps to the Asterisk DIAL command in the asterisk dialplan: http://www.voip-info.org/wiki-Asterisk+cmd+Dial
+        #
+        # The first parameter, number, must be a string that represents the extension or "number" that asterisk should dial.
+        # Be careful to not just specify a number like 5001, 9095551001
+        # You must specify a properly formatted string as Asterisk would expect to use in order to understand
+        # whether the call should be dialed using SIP, IAX, or some other means.
+        # Examples:
+        #
+        # Make a call to the PSTN using my SIP provider for VoIP termination:
+        # dial("SIP/19095551001@my.sip.voip.terminator.us")
+        # 
+        # Make 3 Simulataneous calls to the SIP extensions separated by & symbols, try for 15 seconds and use the callerid
+        # for this call specified by the variable my_callerid
+        # dial "SIP/jay-desk-650&SIP/jay-desk-601&SIP/jay-desk-601-2", :for => 15.seconds, :caller_id => my_callerid
+        #
+        # Make a call using the IAX provider to the PSTN 
+        # dial("IAX2/my.id@voipjet/19095551234", :name=>"John Doe", :caller_id=>"9095551234")
+        #
+        # Options Parameter:
+        # :caller_id - the caller id number to be used when the call is placed.  It is advised you properly adhere to the
+        # policy of VoIP termination providers with respect to caller id values.
+        #
+        # :name - this is the name which should be passed with the caller ID information 
+        # if :name=>"John Doe" and :caller_id => "444-333-1000" then the compelete CID and name would be "John Doe" <4443331000>
+        # support for caller id information varies from country to country and from one VoIP termination provider to another.
+        #
+        # :for - this option can be thought of best as a timeout.  i.e. timeout after :for if no one answers the call
+        # For example, dial("SIP/jay-desk-650&SIP/jay-desk-601&SIP/jay-desk-601-2", :for => 15.seconds, :caller_id => callerid)
+        # this call will timeout after 15 seconds if 1 of the 3 extensions being dialed do not pick prior to the 15 second time limit 
+        #
+        # :options - This is a string of options like "Tr" which are supported by the asterisk DIAL application.
+        # for a complete list of these options and their usage please visit: http://www.voip-info.org/wiki-Asterisk+cmd+Dial
+        #
+        # :confirm - ?
+        # 
         def dial(number, options={})
           *recognized_options = :caller_id, :name, :for, :options, :confirm
           
@@ -635,19 +737,19 @@ module Adhearsion
           end
         
           def interruptable_play(*files)
-            files.each do |file|
+            files.flatten.each do |file|
               result = result_digit_from raw_response("EXEC BACKGROUND #{file}")
               return result if result != 0.chr
             end
             nil
           end
-        
+          
           def set_caller_id_number(caller_id)
             return unless caller_id
             raise ArgumentError, "Caller ID must be numerical" if caller_id.to_s !~ /^\d+$/
             raw_response %(SET CALLERID %p) % caller_id
           end
-
+          
           def set_caller_id_name(caller_id_name)
             return unless caller_id_name
             variable "CALLERID(name)" => caller_id_name