adhearsion 0.8.2 → 0.8.3

data/CHANGELOG

@@ -1,4 +1,11 @@
+0.8.3
+ - The "uniqueid" call channel variable available in dialplan.rb is now *always* a String
+ - Renamed interruptable_play to interruptible_play and made interruptible_play() public instead of protected.
+ - Fixed an Asterisk Manager Interface parsing issue in which colons sometimes got stuck into the key name.
+ - AGI "request" variable coercer will not blow up if no request is given. (Helps in testing with netcat/telnet)
+
 0.8.2
+ - When a call hangs up, Adhearsion will no longer show random exceptions (that were okay) and instead allows the user to rescue a Hangup exception.
  - ManagerInterfaceResponse now include()s DRbUndumped, allowing send_action() to be called directly over DRb.
  - Fixes an inconsequential bug when CTL-C'ing Adhearsion.
 

data/adhearsion.gemspec

@@ -112,7 +112,7 @@ ADHEARSION_FILES = %w{
 
 Gem::Specification.new do |s|
   s.name = "adhearsion"
-  s.version = "0.8.2"
+  s.version = "0.8.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jay Phillips"]

data/app_generators/ahn/templates/components/ami_remote/ami_remote.rb

@@ -2,7 +2,7 @@ methods_for :rpc do
   
   # Simply create proxy methods for the high-level AMI methods
   
-  [:send_action, :introduce, :originate, :call_into_context, :call_and_exec].each do |method_name|
+  [:send_action, :introduce, :originate, :call_into_context, :call_and_exec, :ping].each do |method_name|
     define_method(method_name) do |*args|
       if VoIP::Asterisk.manager_interface
         VoIP::Asterisk.manager_interface.send(method_name, *args)

data/app_generators/ahn/templates/components/disabled/sandbox/sandbox.rb

@@ -29,7 +29,7 @@ initialization do
       
         host, port = config.values_at "host", "port"
       
-        username, password = COMPONENTS.sandbox["username"], COMPONENTS.sandbox["password"]
+        username, password = COMPONENTS.sandbox["username"].to_s, COMPONENTS.sandbox["password"].to_s
         
         if username.blank? || password.blank? || username == "user123"
           ahn_log.sandbox.error "You must specify your username and password in this component's config file!"

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

@@ -5,7 +5,7 @@ unless defined? Adhearsion
     require File.dirname(__FILE__) + "/../adhearsion/lib/adhearsion.rb"
   else  
     require 'rubygems'
-    gem 'adhearsion', '>= 0.7.999'
+    gem 'adhearsion', '>= 0.8.2'
     require 'adhearsion'
   end
 end

data/lib/adhearsion/initializer.rb

@@ -5,7 +5,7 @@ module Adhearsion
     ##
     # Shuts down the framework.
     #
-    def self.shutdown!
+    def shutdown!
       ahn_log "Shutting down gracefully at #{Time.now}."
       Events.stop!
       exit

data/lib/adhearsion/version.rb

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

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

@@ -4,12 +4,12 @@ require 'adhearsion/voip/menu_state_machine/menu_class'
 module Adhearsion
   module VoIP
     module Asterisk
-      module Commands
+      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.
@@ -22,8 +22,8 @@ module Adhearsion
         # 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,
+        # @see http://www.voip-info.org/wiki/index.php?page=Asterisk+variable+DIALSTATUS Asterisk Variable DIALSTATUS
+        DIAL_STATUSES   = Hash.new(:unknown).merge(:answer      => :answered, #:doc:
                                                    :congestion  => :congested, 
                                                    :busy        => :busy,
                                                    :cancel      => :cancelled,
@@ -42,11 +42,13 @@ module Adhearsion
           end
         } unless defined? DYNAMIC_FEATURE_EXTENSIONS
         
-        def write(message)
+	# Utility method to write to pbx.
+        def write(message) 
           to_pbx.print(message)
         end
         
-        def read
+	# Utility method to read from pbx. Hangup if nil.
+        def read 
           returning from_pbx.gets do |message|
             raise Hangup if message.nil?
             ahn_log.agi.debug "<<< #{message}"
@@ -58,7 +60,7 @@ module Adhearsion
         # 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
+        # @see http://www.voip-info.org/wiki/view/Asterisk+FastAGI More information about FAGI
         def raw_response(message = nil)
           ahn_log.agi.debug ">>> #{message}"
           write message if message
@@ -79,8 +81,7 @@ module Adhearsion
         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
+        # which are typically run from extensions.conf.
         #
         # 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
@@ -89,22 +90,19 @@ module Adhearsion
         # 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.
+        # @example Using execute in this way will add a header to an existing SIP call.
+        #   execute 'SIPAddHeader', '"Call-Info: answer-after=0"
         # 
+        # @see http://www.voip-info.org/wiki/view/Asterisk+-+documentation+of+application+commands Asterisk Dialplan Commands
         def execute(application, *arguments)
           result = raw_response("EXEC #{application} #{arguments * '|'}")
           return false if error?(result)
           result
         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.
+        # Hangs up the current channel. After this command is issued, you will not be able to send any more AGI
+        # commands but the dialplan Thread will still continue, allowing you to do any post-call work.
+        #
         def hangup
           raw_response 'HANGUP'
         end
@@ -118,11 +116,13 @@ module Adhearsion
         # file encoded using the current channel's codec, if one exists. If not, it will transcode from
         # the default codec (GSM). Asterisk stores its sound files in /var/lib/asterisk/sounds.
         #
-        # Usage:
-        #
+        # @example Play file hello-world.???
         #   play 'hello-world'
+	# @example Speak current time
         #   play Time.now
+	# @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)
@@ -138,9 +138,11 @@ module Adhearsion
         #
         # Silence and maxduration is specified in seconds.
         #
-        # Usage:
-        #   record
+        # @example Asterisk generated filename
+        #   filename = record
+        # @example Specified filename
         #   record '/path/to/my-file.gsm'
+        # @example All options specified
         #   record 'my-file.gsm', :silence => 5, :maxduration => 120
         #
         def record(*args)
@@ -162,12 +164,13 @@ module Adhearsion
       		execute "SendDTMF", digits.to_s
       	end
       	
+      	# The with_next_message method...
       	def with_next_message(&block)
       	  raise LocalJumpError, "Must supply a block" unless block_given?
       	  block.call(next_message)
     	  end
 
-        # This command shouled be used to advance to the next message in the Asterisk Comedian Voicemail application
+        # This command should be used to advance to the next message in the Asterisk Comedian Voicemail application
         def next_message
           @call.inbox.pop
         end
@@ -177,11 +180,9 @@ module Adhearsion
           not @call.inbox.empty?
         end
 
-        # = Menu Command
+        # Menu creates an interactive menu for the caller.
         #
-        # The following documentation was derived from this blog post on Jay Phillips' blog:
-        # 
-        # http://jicksta.com/articles/2008/02/11/menu-command
+        # The following documentation was derived from a post on Jay Phillips' blog (see below).
         # 
         # The menu() command solves the problem of building enormous input-fetching state machines in Ruby without first-class
         # message passing facilities or an external DSL.
@@ -244,18 +245,18 @@ module Adhearsion
         # hook after the other hook (e.g. +on_invalid+, then +on_failure+).
         # 
         # When the +menu()+ state machine runs through the defined rules, it must distinguish between exact and potential matches.
-        # It’s important to understand the differences between these and how they affect the overall outcome:
+        # It's important to understand the differences between these and how they affect the overall outcome:
         # 
-        # |---------------|-------------------|------------------------------------------------------|
-        # | exact matches |	potential matches	| result                                               |
-        # |---------------|-------------------|------------------------------------------------------|
-        # |  0	          |  0	              | Fail and start over                                  |
-        # |  1	          |  0	              | Match found!                                         |
-        # |  0	          | >0	              | Get another digit                                    |
-        # | >1	          |  0	              | Go with the first exact match                        |
-        # |  1	          | >0	              | Get another digit. If timeout, use exact match       |
-        # | >1	          | >0	              | Get another digit. If timeout, use first exact match |
-        # |---------------|-------------------|------------------------------------------------------|
+        #   |---------------|-------------------|------------------------------------------------------|
+        #   | exact matches |	potential matches	| result                                               |
+        #   |---------------|-------------------|------------------------------------------------------|
+        #   |  0	          |  0	               | Fail and start over                                  |
+        #   |  1	          |  0	               | Match found!                                         |
+        #   |  0	          | >0	               | Get another digit                                    |
+        #   | >1	          |  0	               | Go with the first exact match                        |
+        #   |  1	          | >0	               | Get another digit. If timeout, use exact match       |
+        #   | >1	          | >0	               | Get another digit. If timeout, use first exact match |
+        #   |---------------|-------------------|------------------------------------------------------|
         # 
         # == Database integration
         # 
@@ -290,6 +291,7 @@ module Adhearsion
         # that caused the jump. After all, the context doesn’t necessary need to be the endpoint from a menu; it can be its own entry
         # point, making menu() effectively a pipeline of re-creating the call.
         # 
+        # @see http://jicksta.com/articles/2008/02/11/menu-command Original Blog Post
         def menu(*args, &block)
           options = args.last.kind_of?(Hash) ? args.pop : {}
           sound_files = args.flatten
@@ -407,11 +409,11 @@ module Adhearsion
               buffer << key
               return buffer if number_of_digits && number_of_digits == buffer.length
             end
-            key = wait_for_digit timeout || -1
+            key = wait_for_digit(timeout || -1)
           end
       	end
       	
-        # An alternative to DialplanContextProc#+@. When jumping to a context, it will *not* resume executing
+        # Jumps to a context. An alternative to DialplanContextProc#+@. When jumping to a context, it will *not* resume executing
         # the former context when the jumped-to context has finished executing. Make sure you don't have any
         # +ensure+ closures which you expect to execute when the call has finished, as they will run when
         # this method is called.
@@ -439,6 +441,9 @@ module Adhearsion
           raise Adhearsion::VoIP::DSL::Dialplan::ControlPassingException.new(context)
         end
       	
+      	# The queue method puts a call into a call queue to be answered by an agent registered with that queue.
+      	# The queue method takes a queue_name as an argument to place the caller in the appropriate queue.
+	# @see http://www.voip-info.org/wiki-Asterisk+cmd+Queue Full information on the Asterisk Queue
       	def queue(queue_name)
       	  queue_name = queue_name.to_s
       	  
@@ -523,7 +528,7 @@ module Adhearsion
         # Used to join a particular conference with the MeetMe application. To
         # use MeetMe, be sure you have a proper timing device configured on your
         # Asterisk box. MeetMe is Asterisk's built-in conferencing program.
-        # More info: http://www.voip-info.org/wiki-Asterisk+cmd+MeetMe
+        # @see http://www.voip-info.org/wiki-Asterisk+cmd+MeetMe Asterisk Meetme Application Information
         def join(conference_id, options={})
           conference_id = conference_id.to_s.scan(/\w/).join
           command_flags = options[:options].to_s # This is a passthrough string straight to Asterisk
@@ -536,9 +541,9 @@ module Adhearsion
         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.
+	# @see: http://www.voip-info.org/wiki/view/get+variable Asterisk Get Variable
       	def get_variable(variable_name)
       	  result = raw_response("GET VARIABLE #{variable_name}")
       	  case result
@@ -550,15 +555,18 @@ module Adhearsion
     	  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.
+    	  # @see http://www.voip-info.org/wiki/view/set+variable Asterisk Set Variable
     	  def set_variable(variable_name, value)
     	    raw_response("SET VARIABLE %s %p" % [variable_name.to_s, value.to_s]) == "200 result=1"
   	    end
     	  
+    	  # The variable method allows you to either set or get a channel variable from Asterisk
+    	  # The method takes a hash key/value pair if you would like to set a variable
+    	  # Or a single string with the variable to get from Asterisk
     	  def variable(*args)
     	    if args.last.kind_of? Hash
       	    assignments = args.pop
@@ -575,6 +583,10 @@ module Adhearsion
     	    end
   	    end
     	  
+    	  # Use the voicemail method to send a caller to a voicemail box to leave a message. 
+    	  # @see http://www.voip-info.org/tiki-index.php?page=Asterisk+cmd+VoiceMail Asterisk Voicemail
+    	  # The method takes the mailbox_number of the user to leave a message for and a
+    	  # greeting_option that will determine which message gets played to the caller.
         def voicemail(*args)
           options_hash    = args.last.kind_of?(Hash) ? args.pop : {}
           mailbox_number  = args.shift
@@ -607,6 +619,9 @@ module Adhearsion
           end
         end
         
+        # The voicemail_main method puts a caller into the voicemail system to fetch their voicemail
+        # or set options for their voicemail box.
+        # @see http://www.voip-info.org/wiki-Asterisk+cmd+VoiceMailMain Asterisk VoiceMailMain Command
         def voicemail_main(options={})
           mailbox, context, folder = options.values_at :mailbox, :context, :folder
           authenticate = options.has_key?(:authenticate) ? options[:authenticate] : true
@@ -643,42 +658,43 @@ 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
+        # Use this command to dial an extension or "phone number" in asterisk.
+        # This command maps to the Asterisk DIAL command in the asterisk dialplan. 
         #
         # 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
+        #
+        # +: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 
+        # +: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+ - 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 
+        # 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
+        # +: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 check the link below.
         #
-        # :confirm - ?
+        # +:confirm+ - ?
+	#
+        # @example Make a call to the PSTN using my SIP provider for VoIP termination
+        #   dial("SIP/19095551001@my.sip.voip.terminator.us")
         # 
+        # @example 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
+        #
+        # @example Make a call using the IAX provider to the PSTN 
+        #   dial("IAX2/my.id@voipjet/19095551234", :name=>"John Doe", :caller_id=>"9095551234")
+        #
+	# @see http://www.voip-info.org/wiki-Asterisk+cmd+Dial Asterisk Dial Command
         def dial(number, options={})
           *recognized_options = :caller_id, :name, :for, :options, :confirm
           
@@ -728,29 +744,44 @@ module Adhearsion
           yield
           Time.now - start_time
         end
+        
+        #
+        # This will play a sequence of files, stopping the playback if a digit is pressed. If a digit is pressed, it will be
+        # returned as a String. If the files played with no keypad input, nil will be returned.
+        #
+        def interruptible_play(*files)
+          files.flatten.each do |file|
+            result = result_digit_from raw_response("EXEC BACKGROUND #{file}")
+            return result if result != 0.chr
+          end
+          nil
+        end
 
         protected
         
+          # wait_for_digits waits for the input of digits based on the number of milliseconds
           def wait_for_digit(timeout=-1)
             timeout *= 1_000 if timeout != -1
             result = result_digit_from raw_response("WAIT FOR DIGIT #{timeout.to_i}")
             (result == 0.chr) ? nil : result
           end
         
+          ##
+          # Deprecated name of interruptible_play(). This is a misspelling!
+          #
           def interruptable_play(*files)
-            files.flatten.each do |file|
-              result = result_digit_from raw_response("EXEC BACKGROUND #{file}")
-              return result if result != 0.chr
-            end
-            nil
+            ahn_log.deprecation.warn 'Please change your code to use interruptible_play() instead. "interruptable" is a misspelling! interruptable_play() will work for now but will be deprecated in the future!'
+            interruptible_play(*files)
           end
           
+          # set_callier_id_number method 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+$/
             raw_response %(SET CALLERID %p) % caller_id
           end
           
+          # set_caller_id_name method allows the setting of the callerid name of the call
           def set_caller_id_name(caller_id_name)
             return unless caller_id_name
             variable "CALLERID(name)" => caller_id_name
@@ -902,8 +933,8 @@ module Adhearsion
           
           # timeout with pressed digits:    200 result=<digits> (timeout)
           # timeout without pressed digits: 200 result= (timeout)
-          # (http://www.voip-info.org/wiki/view/get+data)
-          def input_timed_out?(result)
+          # @see http://www.voip-info.org/wiki/view/get+data AGI Get Data
+         def input_timed_out?(result)
             result.starts_with?(response_prefix) && result.ends_with?('(timeout)')
           end