adhearsion 1.0.0 → 1.0.1

data/app_generators/ahn/ahn_generator.rb

@@ -49,6 +49,7 @@ class AhnGenerator < RubiGen::Base
       m.file  *["events.rb"]*2
       m.file  *["README"]*2
       m.file  *["Rakefile"]*2
+      m.file  *["Gemfile"]*2
 
       # m.dependency "install_rubigen_scripts", [destination_root, 'ahn', 'adhearsion', 'test_spec'],
       #   :shebang => options[:shebang], :collision => :force

data/app_generators/ahn/templates/Gemfile

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+
+gem "rake"
+gem "rubigen", ">= 1.0.6"
+gem "log4r", ">= 1.0.5"
+gem "activesupport", ">= 2.1.0"
+gem "adhearsion", ">= 1.0.1"

data/app_generators/ahn/templates/Rakefile

@@ -1,9 +1,11 @@
 # This file is for the "rake" tool which automates project-related tasks. If you need to automate things, you can create
 # a new Rake task here. See http://rake.rubyforge.org for more info.
 require 'rubygems'
+require 'bundler'
+Bundler.setup
+Bundler.require
 
 begin
-  require 'adhearsion'
   require 'adhearsion/tasks'
 rescue LoadError
   STDERR.puts "\nCannot load Adhearsion! Not all Rake tasks will be loaded!\n\n"
@@ -22,4 +24,4 @@ task :gitignore do
       end
     end
   end
-end
+end

data/app_generators/ahn/templates/config/startup.rb

@@ -1,16 +1,7 @@
-unless defined? Adhearsion
-  if File.exists? File.dirname(__FILE__) + "/../adhearsion/lib/adhearsion.rb"
-    # For development purposes try to load a local copy of Adhearsion here.
-    # This will not work if started using "ahn" or "jahn".  You must execute
-    # config/startup.rb directly and have a local checkout of Adhearsion in your
-    # application directory.
-    require File.dirname(__FILE__) + "/../adhearsion/lib/adhearsion.rb"
-  else
-    require 'rubygems'
-    gem 'adhearsion', '>= 0.8.2'
-    require 'adhearsion'
-  end
-end
+require 'rubygems'
+require 'bundler'
+Bundler.setup
+Bundler.require
 
 Adhearsion::Configuration.configure do |config|
 
@@ -71,7 +62,7 @@ Adhearsion::Configuration.configure do |config|
   #                    :password => 'password12345',
   #                    :allow_anonymous => false,
   #                    :try_sasl => false
-  
+
   # Configure XMPP call controller
   # config.enable_xmpp :jid => 'active-calls.xmpp.example.com',
   #                    :password => 'passwd',

data/bin/ahn

@@ -22,6 +22,7 @@
 $:.unshift File.expand_path(File.dirname(__FILE__) + "/../lib")
 
 require 'rubygems'
+require 'bundler/setup'
 require 'adhearsion'
 require 'adhearsion/cli'
 

data/bin/jahn

@@ -22,6 +22,7 @@
 $:.unshift File.expand_path(File.dirname(__FILE__) + "/../lib")
 
 require 'rubygems'
+require 'bundler/setup'
 require 'adhearsion'
 require 'adhearsion/cli'
 

data/lib/adhearsion.rb

@@ -6,6 +6,7 @@ Please upgrade to at least Ruby v1.8.5." if RUBY_VERSION < "1.8.5"
 $: << File.expand_path(File.dirname(__FILE__))
 
 require 'rubygems'
+require 'bundler/setup'
 
 require 'adhearsion/version'
 require 'adhearsion/voip/call'

data/lib/adhearsion/cli.rb

@@ -14,23 +14,24 @@ Usage:
    ahn disable component COMPONENT_NAME
    ahn  create component COMPONENT_NAME
 USAGE
+      class << self
 
-      def self.execute!
-        CommandHandler.send(*parse_arguments)
-      rescue CommandHandler::CLIException => error
-        fail_and_print_usage error
-      end
+        def execute!
+          CommandHandler.send(*parse_arguments)
+        rescue CommandHandler::CLIException => error
+          fail_and_print_usage error
+        end
 
-      ##
-      # Provides a small abstraction of Kernel::abort().
-      #
-      def self.fail_and_print_usage(error)
-        Kernel.abort "#{error.message}\n\n#{USAGE}"
-      end
+        ##
+        # Provides a small abstraction of Kernel::abort().
+        #
+        def fail_and_print_usage(error)
+          Kernel.abort "#{error.message}\n\n#{USAGE}"
+        end
 
-      def self.parse_arguments(args=ARGV.clone)
-        action = args.shift
-        case action
+        def parse_arguments(args=ARGV.clone)
+          action = args.shift
+          case action
           when /^-?-?h(elp)?$/, nil   then [:help]
           when /^-?-?v(ersion)?$/     then [:version]
           when "create"
@@ -67,6 +68,7 @@ USAGE
             end
           else
             [action, *args]
+          end
         end
       end
 
@@ -102,23 +104,72 @@ USAGE
 
               app_path = PathString.from_application_subdirectory Dir.pwd
 
-              raise PathInvalid.new(Dir.pwd) if app_path.nil?
+              if app_path.nil?
+                new_component_dir = File.join Dir.pwd, component_name
+              else
+                puts "Adhearsion application detected. Creating new component at components/#{component_name}"
+                new_component_dir = File.join app_path, "components", component_name
+              end
 
-              new_component_dir = app_path + "/components/#{component_name}"
               raise ComponentError.new("Component #{component_name} already exists!") if File.exists?(new_component_dir)
 
               # Everything's good. Let's create the component
               Dir.mkdir new_component_dir
-              File.open(new_component_dir + "/#{component_name}.rb","w") do |file|
+
+              # Initial component code file
+              Dir.mkdir File.join(new_component_dir, "lib")
+              fn = File.join("lib", "#{component_name}.rb")
+              puts "- #{fn}: Initial component code file"
+              File.open(File.join(new_component_dir, fn),"w") do |file|
                 file.puts <<-RUBY
 # See http://docs.adhearsion.com for more information on how to write components or
 # look at the examples in newly-created projects.
                 RUBY
               end
-              File.open(new_component_dir + "/#{component_name}.yml","w") do |file|
+
+              # Component configuration
+              Dir.mkdir File.join(new_component_dir, "config")
+              fn = File.join("config", "#{component_name}.yml")
+              puts "- #{fn}: Example component configuration YAML"
+              File.open(File.join(new_component_dir, fn),"w") do |file|
                 file.puts '# You can use this file for component-specific configuration.'
               end
-              puts "Created blank component '#{component_name}' at components/#{component_name}"
+
+              # Component example gemspec
+              fn = File.join("#{component_name}.gemspec")
+              puts "- #{fn}: Example component gemspec"
+              File.open(File.join(new_component_dir, fn), "w") do |file|
+                file.puts <<-RUBY
+GEM_FILES = %w{
+  #{component_name}.gemspec
+  lib/#{component_name}.rb
+  config/#{component_name}.yml
+}
+
+Gem::Specification.new do |s|
+  s.name = "#{component_name}"
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Your Name Here!"]
+
+  s.date = Date.today.to_s
+  s.description = "This Adhearsion component gem has not yet been described."
+  s.email = "noreply@example.com"
+
+  s.files = GEM_FILES
+
+  s.has_rdoc = false
+  s.homepage = "http://adhearsion.com"
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.2.0"
+  s.summary = "This Adhearsion component gem has no summary."
+
+  s.specification_version = 2
+end
+                RUBY
+              end
+              puts "Created blank component '#{component_name}' at #{new_component_dir}"
             else
               raise CommandHandler::UnknownCommand.new("Provided too many arguments to 'create'")
             end

data/lib/adhearsion/foundation/blank_slate.rb

@@ -1,3 +1,3 @@
 class BlankSlate
-  (instance_methods - %w{instance_eval object_id}).each { |m| undef_method m unless m =~ /^__/ }
-end
+  (instance_methods.map{|m| m.to_sym} - [:instance_eval, :object_id]).each { |m| undef_method m unless m.to_s =~ /^__/ }
+end

data/lib/adhearsion/foundation/event_socket.rb

@@ -167,6 +167,7 @@ class EventSocket
   def new_handler_from_block(&handler_block)
     handler = Object.new
     handler.metaclass.send :attr_accessor, :set_callbacks
+    handler.metaclass.send :public, :set_callbacks, :set_callbacks=
     handler.set_callbacks = {:receive_data => false, :disconnected => false, :connected => false }
 
     def handler.receive_data(&block)

data/lib/adhearsion/initializer/configuration.rb

@@ -246,8 +246,8 @@ module Adhearsion
 
         unless acl
           self.acl = []
-          overrides[ :deny].to_a.each { |ip| acl << 'deny' << ip }
-          overrides[:allow].to_a.each { |ip| acl << 'allow' << ip }
+          [*overrides[ :deny]].compact.each { |ip| acl << 'deny' << ip }
+          [*overrides[:allow]].compact.each { |ip| acl << 'allow' << ip }
           acl.concat %w[allow 127.0.0.1] if acl.empty?
         end
       end

data/lib/adhearsion/version.rb

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

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

@@ -36,7 +36,7 @@ module Adhearsion
             variable "TRANSFER_CONTEXT" => options[:context] if options && options.has_key?(:context)
             extend_dynamic_features_with "atxfer"
           end,
-          :blind_transfer => lambda do
+          :blind_transfer => lambda do |options|
             variable "TRANSFER_CONTEXT" => options[:context] if options && options.has_key?(:context)
             extend_dynamic_features_with 'blindxfer'
           end
@@ -174,7 +174,9 @@ module Adhearsion
         # Plays the specified sound file names. This method will handle Time/DateTime objects (e.g. Time.now),
         # Fixnums (e.g. 1000), Strings which are valid Fixnums (e.g "123"), and direct sound files. When playing
         # numbers, Adhearsion assumes you're saying the number, not the digits. For example, play("100")
-        # is pronounced as "one hundred" instead of "one zero zero".
+        # is pronounced as "one hundred" instead of "one zero zero". To specify how the Date/Time objects are said
+        # pass in as an array with the first parameter as the Date/Time/DateTime object along with a hash with the 
+        # additional options.  See play_time for more information.
         #
         # Note: it is not necessary to supply a sound file extension; Asterisk will try to find a sound
         # file encoded using the current channel's codec, if one exists. If not, it will transcode from
@@ -184,13 +186,17 @@ module Adhearsion
         #   play 'hello-world'
         # @example Speak current time
         #   play Time.now
+        # @example Speak today's date
+        #   play Date.today
+        # @example Speak today's date in a specific format
+        #   play [Date.today, {:format => 'BdY'}]
         # @example Play sound file, speak number, play two more sound files
         #   play %w"a-connect-charge-of 22 cents-per-minute will-apply"
         # @example Play two sound files
         #   play "you-sound-cute", "what-are-you-wearing"
         #
         def play(*arguments)
-          arguments.flatten.each do |argument|
+          arguments.each do |argument|
             play_time(argument) || play_numeric(argument) || play_string(argument)
           end
         end
@@ -911,6 +917,62 @@ module Adhearsion
           nil
         end
 
+        ##
+        # Executes the SayPhonetic command. This command will read the text passed in 
+        # out load using the NATO phonetic alphabet.
+        #
+        # @param [String] Passed in as the text to read aloud
+        #
+        # @see http://www.voip-info.org/wiki/view/Asterisk+cmd+SayPhonetic Asterisk SayPhonetic Command
+        def say_phonetic(text)
+          execute "sayphonetic", text
+        end
+
+        ##
+        # Executes the SayAlpha command. This command will read the text passed in
+        # out loud, character-by-character.
+        #
+        # @param [String] Passed in as the text to read aloud
+        #
+        # @example Say "one a two dot pound"
+        #   say_chars "1a2.#"
+        #
+        # @see http://www.voip-info.org/wiki/view/Asterisk+cmd+SayAlpha Asterisk SayPhonetic Command
+        def say_chars(text)
+          execute "sayalpha", text
+        end
+
+        # Plays the given Date, Time, or Integer (seconds since epoch)
+        # using the given timezone and format.
+        #
+        # @param [Date|Time|DateTime] Time to be said.
+        # @param [Hash] Additional options to specify how exactly to say time specified.
+        #
+        # +:timezone+ - Sends a timezone to asterisk. See /usr/share/zoneinfo for a list. Defaults to the machine timezone.
+        # +:format+   - This is the format the time is to be said in.  Defaults to "ABdY 'digits/at' IMp"
+        #
+        # @see http://www.voip-info.org/wiki/view/Asterisk+cmd+SayUnixTime
+        def play_time(*args)
+          argument, options = args.flatten
+          options ||= {}
+
+          timezone = options.delete(:timezone) || ''
+          format   = options.delete(:format)   || ''
+          epoch    = case argument.class.to_s
+                     when 'Time'      then argument.to_i
+                     when 'DateTime'  then argument.to_i
+                     when 'Date'
+                       format = 'BdY' unless format.present?
+                       argument.to_time.to_i
+                     else
+                       nil
+                     end
+
+          return false if epoch.nil?
+
+          execute(:sayunixtime, epoch, timezone, format)
+        end
+
         protected
 
           # wait_for_digits waits for the input of digits based on the number of milliseconds
@@ -929,10 +991,10 @@ module Adhearsion
           end
 
           # allows setting of the callerid number of the call
-          def set_caller_id_number(caller_id)
-            return unless caller_id
-            raise ArgumentError, "Caller ID must be numerical" if caller_id.to_s !~ /^\d+$/
-            response "SET CALLERID", caller_id
+          def set_caller_id_number(caller_id_num)
+            return unless caller_id_num
+            raise ArgumentError, "Caller ID must be numeric" if caller_id_num.to_s !~ /^\d+$/
+            variable "CALLERID(num)" => caller_id_num
           end
 
           # allows the setting of the callerid name of the call
@@ -1016,11 +1078,6 @@ module Adhearsion
             dial_status ? dial_status.downcase.to_sym : :cancelled
           end
 
-          def play_time(argument)
-            if argument.kind_of? Time
-              execute(:sayunixtime, argument.to_i)
-            end
-          end
 
           def play_numeric(argument)
             if argument.kind_of?(Numeric) || argument =~ /^\d+$/
@@ -1118,6 +1175,7 @@ module Adhearsion
                 ring_style     = options.delete :play
                 allow_hangup   = options.delete :allow_hangup
                 allow_transfer = options.delete :allow_transfer
+                agi            = options.delete :agi
 
                 raise ArgumentError, "Unrecognized args to join!: #{options.inspect}" if options.any?
 
@@ -1146,7 +1204,7 @@ module Adhearsion
 
                 terse_character_options = ring_style + allow_transfer + allow_hangup
 
-                [terse_character_options, '', announcement, timeout].map(&:to_s)
+                [terse_character_options, '', announcement, timeout, agi].map(&:to_s)
               end
 
             end
@@ -1165,6 +1223,7 @@ module Adhearsion
             #   :announce       - A sound file to play instead of the normal queue announcement.
             #   :allow_transfer - Can be :caller, :agent, or :everyone. Allow someone to transfer the call.
             #   :allow_hangup   - Can be :caller, :agent, or :everyone. Allow someone to hangup with the * key.
+            #   :agi            - An AGI script to be called on the calling parties channel just before being connected.
             #
             #  @example
             #    queue('sales').join!
@@ -1187,6 +1246,8 @@ module Adhearsion
             #  @example
             #    queue('sales').join! :allow_hangup   => :everyone
             #  @example
+            #    queue('sales').join! :agi            => 'agi://localhost/sales_queue_callback'
+            #  @example
             #    queue('sales').join! :allow_transfer => :agent, :timeout => 30.seconds,
             def join!(options={})
               environment.execute("queue", name, *self.class.format_join_hash_key_arguments(options))
@@ -1240,23 +1301,24 @@ module Adhearsion
             #
             # According to http://www.voip-info.org/wiki/view/Asterisk+cmd+Queue
             # possible values are:
-            # TIMEOUT (:timeout
-            # FULL (:full)
-            # JOINEMPTY (:joinempty)
-            # LEAVEEMPTY (:leaveempty)
-            # JOINUNAVAIL (:joinunavail)
-            # LEAVEUNAVAIL (:leaveunavail)
             #
-            # If Adhearsion cannot determine the status then :unknown will be returned.
+            # TIMEOUT      => :timeout
+            # FULL         => :full
+            # JOINEMPTY    => :joinempty
+            # LEAVEEMPTY   => :leaveempty
+            # JOINUNAVAIL  => :joinunavail
+            # LEAVEUNAVAIL => :leaveunavail
+            # CONTINUE     => :continue
+            #
+            # If the QUEUESTATUS variable is not set the call was successfully connected, 
+            # and Adhearsion will return :completed.
             #
             # @param [String] QUEUESTATUS variable from Asterisk
             # @return [Symbol] Symbolized version of QUEUESTATUS
             # @raise QueueDoesNotExistError
             def normalize_queue_status_variable(variable)
-              variable = "UNKNOWN" if variable.nil?
-              variable.downcase.to_sym.tap do |queue_status|
-                raise QueueDoesNotExistError.new(name) if queue_status == :unknown
-              end
+              variable = "COMPLETED" if variable.nil?
+              variable.downcase.to_sym
             end
 
             class QueueAgentsListProxy
@@ -1285,26 +1347,35 @@ module Adhearsion
               def new(*args)
 
                 options   = args.last.kind_of?(Hash) ? args.pop : {}
-                interface = args.shift || ''
+                interface = args.shift
 
+                raise ArgumentError, "You must specify an interface to add." if interface.nil?
                 raise ArgumentError, "You may only supply an interface and a Hash argument!" if args.any?
 
-                penalty = options.delete(:penalty) || ''
-                name    = options.delete(:name)    || ''
+                penalty             = options.delete(:penalty)            || ''
+                name                = options.delete(:name)               || ''
+                state_interface     = options.delete(:state_interface)    || ''
 
                 raise ArgumentError, "Unrecognized argument(s): #{options.inspect}" if options.any?
 
-                proxy.environment.execute("AddQueueMember", proxy.name, interface, penalty, '', name)
+                proxy.environment.execute("AddQueueMember", proxy.name, interface, penalty, '', name, state_interface)
 
-                case proxy.environment.variable("AQMSTATUS")
-                  when "ADDED"         then true
-                  when "MEMBERALREADY" then false
-                  when "NOSUCHQUEUE"   then raise QueueDoesNotExistError.new(proxy.name)
-                  else
-                    raise "UNRECOGNIZED AQMSTATUS VALUE!"
-                end
+                added = case proxy.environment.variable("AQMSTATUS")
+                        when "ADDED"         then true
+                        when "MEMBERALREADY" then false
+                        when "NOSUCHQUEUE"   then raise QueueDoesNotExistError.new(proxy.name)
+                        else
+                          raise "UNRECOGNIZED AQMSTATUS VALUE!"
+                        end
 
-                # TODO: THIS SHOULD RETURN AN AGENT INSTANCE
+                if added
+                  check_agent_cache!
+                  AgentProxy.new(interface, proxy).tap do |agent_proxy|
+                    @agents << agent_proxy
+                  end
+                else
+                  false
+                end
               end
 
               # Logs a pre-defined agent into this queue and waits for calls. Pass in :silent => true to stop