adhearsion-cw 1.0.2.1

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

@@ -0,0 +1,1581 @@
+
+require 'adhearsion/voip/menu_state_machine/menu_class'
+
+module Adhearsion
+  module VoIP
+    module Asterisk
+      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.
+        #
+        # 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)
+        #
+        # @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,
+                                                   :noanswer    => :unanswered,
+                                                   :cancelled   => :cancelled,
+                                                   :chanunavail => :channel_unavailable) unless defined? DIAL_STATUSES
+
+        DYNAMIC_FEATURE_EXTENSIONS = {
+          :attended_transfer => lambda do |options|
+            variable "TRANSFER_CONTEXT" => options[:context] if options && options.has_key?(:context)
+            extend_dynamic_features_with "atxfer"
+          end,
+          :blind_transfer => lambda do |options|
+            variable "TRANSFER_CONTEXT" => options[:context] if options && options.has_key?(:context)
+            extend_dynamic_features_with 'blindxfer'
+          end
+        } unless defined? DYNAMIC_FEATURE_EXTENSIONS
+
+        # Utility method to write to pbx.
+        # @param [String] message raw message
+        def write(message)
+          to_pbx.print(message + "\n")
+        end
+
+        # Utility method to read from pbx. Hangup if nil.
+        def read
+          from_pbx.gets.tap do |message|
+            # AGI has many conditions that might indicate a hangup
+            raise Hangup if message.nil?
+
+            ahn_log.agi.debug "<<< #{message}"
+
+            code, rest = *message.split(' ', 2)
+
+            case code.to_i
+            when 510
+              # This error is non-fatal for the call
+              ahn_log.agi.warn "510: Invalid or unknown AGI command"
+            when 511
+              # 511 Command Not Permitted on a dead channel
+              ahn_log.agi.debug "511: Dead channel. Raising Hangup"
+              raise Hangup
+            when 520
+              # This error is non-fatal for the call
+              ahn_log.agi.warn "520: Invalid command syntax"
+            when (500..599)
+              # Assume this error is non-fatal for the call and try to keep running
+              ahn_log.agi.warn "#{code}: Unknown AGI protocol error."
+            end
+
+            # If the message starts with HANGUP it's a silly 1.6 OOB message
+            case message
+            when /^HANGUP/, /^HANGUP\n?$/i, /^HANGUP\s?\d{3}/i
+              ahn_log.agi.debug "AGI HANGUP. Raising hangup"
+              raise Hangup
+            end
+          end
+        end
+
+        # The underlying method executed by nearly all the command methods in this module.
+        # 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 to communicate directly with an Asterisk server via the FAGI protocol.
+        #
+        # @param [String] message
+        #
+        # @see http://www.voip-info.org/wiki/view/Asterisk+FastAGI More information about FAGI
+        def raw_response(message = nil)
+          raise ArgumentError.new("illegal NUL in message #{message.inspect}") if message =~ /\0/
+          ahn_log.agi.debug ">>> #{message}"
+          write message if message
+          read
+        end
+
+        def response(command, *arguments)
+          # Arguments surrounded by quotes; quotes backslash-escaped.
+          # See parse_args in asterisk/res/res_agi.c (Asterisk 1.4.21.1)
+          quote_arg = lambda { |arg|
+            '"' + arg.gsub(/["\\]/) { |m| "\\#{m}" } + '"'
+          }
+          if arguments.empty?
+            raw_response("#{command}")
+          else
+            raw_response("#{command} " + arguments.map{ |arg| quote_arg.call(arg.to_s) }.join(' '))
+          end
+        end
+
+        # This must be called first before any other commands can be issued.
+        # In typical Adhearsion applications this 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 one has already
+        # been issued either explicitly by your code or implicitly by the standard adhearsion configuration.
+        def answer
+          response "ANSWER"
+          true
+        end
+
+        # This asterisk dialplan command allows you to instruct Asterisk to start applications
+        # 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
+        # should use.
+        #
+        # For example, if there are specific asterisk modules you have loaded that will not be
+        # available through the standard commands provided through FAGI - then you can used EXEC.
+        #
+        # @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 %s "%s"} % [ application,
+            arguments.join(%{"#{AHN_CONFIG.asterisk.argument_delimiter}"}) ])
+          return false if error?(result)
+          result
+        end
+
+        # Sends a message to the console via the verbose message system.
+        #
+        # @param [String] message
+        # @param [Integer] level
+        #
+        # @return the result of the command
+        #
+        # @example Use this command to inform someone watching the Asterisk console
+        # of actions happening within Adhearsion.
+        #   verbose 'Processing call with Adhearsion' 3
+        #
+        # @see http://www.voip-info.org/wiki/view/verbose
+        def verbose(message, level = nil)
+            result = raw_response("VERBOSE \"#{message}\" #{level}")
+            return false if error?(result)
+            result
+        end
+
+        # 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
+          response 'HANGUP'
+        end
+
+        # 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". 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
+        # the default codec (GSM). Asterisk stores its sound files in /var/lib/asterisk/sounds.
+        #
+        # @example Play file hello-world.???
+        #   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.each do |argument|
+            play_time(argument) || play_numeric(argument) || play_string(argument)
+          end
+        end
+
+        # Records a sound file with the given name. If no filename is specified a file named by Asterisk
+        # will be created and returned. Else the given filename will be returned. If a relative path is
+        # given, the file will be saved in the default Asterisk sound directory, /var/lib/spool/asterisk
+        # by default.
+        #
+        # Silence and maxduration is specified in seconds.
+        #
+        # @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)
+          options = args.last.kind_of?(Hash) ? args.pop : {}
+          filename = args.shift || "/tmp/recording_%d"
+
+          if filename.index("%d")
+            if @call.variables.has_key?(:recording_counter)
+              @call.variables[:recording_counter] += 1
+            else
+              @call.variables[:recording_counter]  = 0
+            end
+            filename = filename % @call.variables[:recording_counter]
+          end
+
+          if (!options.has_key?(:format))
+            format = filename.slice!(/\.[^\.]+$/)
+            if (format.nil?)
+              ahn_log.agi.warn "Format not specified and not detected.  Defaulting to \"gsm\""
+              format = "gsm"
+            end
+            format.sub!(/^\./, "")
+          else
+            format = options.delete(:format)
+          end
+
+          # maxduration must be in milliseconds when using RECORD FILE
+          maxduration = options.delete(:maxduration) || -1
+          maxduration = maxduration * 1000 if maxduration > 0
+
+          escapedigits = options.delete(:escapedigits) || "#"
+          silence     = options.delete(:silence) || 0
+
+          if (silence > 0)
+            response("RECORD FILE", filename, format, escapedigits, maxduration, 0, "BEEP", "s=#{silence}")
+          else
+            response("RECORD FILE", filename, format, escapedigits, maxduration, 0, "BEEP")
+          end
+
+          # If the user hangs up before the recording is entered, -1 is returned and RECORDED_FILE
+          # will not contain the name of the file, even though it IS in fact recorded.
+          filename + "." + format
+        end
+
+        # Simulates pressing the specified digits over the current channel. Can be used to
+        # traverse a phone menu.
+        def dtmf(digits)
+          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 should 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
+
+        # Creates an interactive menu for the caller.
+        #
+        # 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.
+        #
+        # Here is an example dialplan which uses the menu() command effectively.
+        #
+        #   from_pstn {
+        #     menu 'welcome', 'for-spanish-press-8', 'main-ivr',
+        #          :timeout => 8.seconds, :tries => 3 do |link|
+        #       link.shipment_status  1
+        #       link.ordering         2
+        #       link.representative   4
+        #       link.spanish          8
+        #       link.employee         900..999
+        #
+        #       link.on_invalid { play 'invalid' }
+        #
+        #       link.on_premature_timeout do |str|
+        #         play 'sorry'
+        #       end
+        #
+        #       link.on_failure do
+        #         play 'goodbye'
+        #         hangup
+        #       end
+        #     end
+        #   }
+        #
+        #   shipment_status {
+        #     # Fetch a tracking number and pass it to a web service.
+        #   }
+        #
+        #   ordering {
+        #     # Enter another menu that lets them enter credit card
+        #     # information and place their order over the phone.
+        #   }
+        #
+        #   representative {
+        #     # Place the caller into a queue
+        #   }
+        #
+        #   spanish {
+        #     # Special options for the spanish menu.
+        #   }
+        #
+        #   employee {
+        #     dial "SIP/#{extension}" # Overly simplistic
+        #   }
+        #
+        # The main detail to note is the declarations within the menu() command’s block. Each line seems to refer to a link object
+        # executing a seemingly arbitrary method with an argument that’s either a number or a Range of numbers. The +link+ object
+        # collects these arbitrary method invocations and assembles a set of rules. The seemingly arbitrary method name is the name
+        # of the context to which the menu should jump in case its argument (the pattern) is found to be a match.
+        #
+        # With these context names and patterns defined, the +menu()+ command plays in sequence the sound files you supply as
+        # arguments, stopping playback abruptly if the user enters a digit. If no digits were pressed when the files finish playing,
+        # it waits +:timeout+ seconds. If no digits are pressed after the timeout, it executes the +on_premature_timeout+ hook you
+        # define (if any) and then tries again a maximum of +:tries+ times. If digits are pressed that result in no possible match,
+        # it executes the +on_invalid+ hook. When/if all tries are exhausted with no positive match, it executes the +on_failure+
+        # 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:
+        #
+        #   |---------------|-------------------|------------------------------------------------------|
+        #   | 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
+        #
+        # To do database integration, I recommend programatically executing methods on the link object within the block. For example:
+        #
+        #   menu do |link|
+        #     for employee in Employee.find(:all)
+        #       link.internal employee.extension
+        #     end
+        #   end
+        #
+        # or this more efficient and Rubyish way
+        #
+        #   menu do |link|
+        #     link.internal *Employee.find(:all).map(&:extension)
+        #   end
+        #
+        # If this second example seems like too much Ruby magic, let me explain — +Employee.find(:all)+ effectively does a “SELECT *
+        # FROM employees” on the database with ActiveRecord, returning (what you’d think is) an Array. The +map(&:extension)+ is
+        # fanciness that means “replace every instance in this Array with the result of calling extension on that object”. Now we
+        # have an Array of every extension in the database. The splat operator (*) before the argument changes the argument from
+        # being one argument (an Array) into a sequence of n arguments, where n is the number of items in the Array it’s “splatting”.
+        # Lastly, these arguments are passed to the internal method, the name of a context which will handle dialing this user if one
+        # of the supplied patterns matches.
+        #
+        # == Handling a successful pattern match
+        #
+        # Which brings me to another important note. Let’s say that the user’s input successfully matched one of the patterns
+        # returned by that Employe.find... magic. When it jumps to the internal context, that context can access the variable entered
+        # through the extension variable. This was a tricky design decision that I think, overall, works great. It makes the +menu()+
+        # command feel much more first-class in the Adhearsion dialplan grammar and decouples the receiving context from the menu
+        # 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
+
+          menu_instance = Menu.new(options, &block)
+
+          initial_digit_prompt = sound_files.any?
+
+          # This method is basically one big begin/rescue block. When we start the Menu state machine by continue()ing, the state
+          # machine will pass messages back to this method in the form of Exceptions. This decoupling allows the menu system to
+          # work on, say, Freeswitch and Asterisk both.
+          begin
+            if menu_instance.should_continue?
+              menu_instance.continue
+            else
+              menu_instance.execute_failure_hook
+              return :failed
+            end
+          rescue Menu::MenuResult => result_of_menu
+            case result_of_menu
+              when Menu::MenuResultInvalid
+                menu_instance.execute_invalid_hook
+                menu_instance.restart!
+              when Menu::MenuGetAnotherDigit
+
+                next_digit = play_sound_files_for_menu(menu_instance, sound_files)
+                if next_digit
+                  menu_instance << next_digit
+                else
+                  # The user timed out entering another digit!
+                  case result_of_menu
+                    when Menu::MenuGetAnotherDigitOrFinish
+                      # This raises a ControlPassingException
+                      jump_to result_of_menu.match_payload, :extension => result_of_menu.new_extension
+                    when Menu::MenuGetAnotherDigitOrTimeout
+                      # This should execute premature_timeout AND reset if the number of retries
+                      # has not been exhausted.
+                      menu_instance.execute_timeout_hook
+                      menu_instance.restart!
+                  end
+                end
+              when Menu::MenuResultFound
+                jump_to result_of_menu.match_payload, :extension => result_of_menu.new_extension
+              else
+                raise "Unrecognized MenuResult! This may be a bug!"
+            end
+
+            # Retry will re-execute the begin block, preserving our changes to the menu_instance object.
+            retry
+
+          end
+        end
+
+        # Used to receive keypad input from the user. Digits are collected
+        # via DTMF (keypad) input until one of three things happens:
+        #
+        #  1. The number of digits you specify as the first argument is collected
+        #  2. The timeout you specify with the :timeout option elapses.
+        #  3. The "#" key (or the key you specify with :accept_key) is pressed
+      	#
+      	# Usage examples
+      	#
+      	#   input   # Receives digits until the caller presses the "#" key
+      	#   input 3 # Receives three digits. Can be 0-9, * or #
+      	#   input 5, :accept_key => "*"   # Receive at most 5 digits, stopping if '*' is pressed
+      	#   input 1, :timeout => 1.minute # Receive a single digit, returning an empty
+      	#                                   string if the timeout is encountered
+      	#   input 9, :timeout => 7, :accept_key => "0" # Receives nine digits, returning
+      	#                                              # when the timeout is encountered
+      	#                                              # or when the "0" key is pressed.
+      	#   input 3, :play => "you-sound-cute"
+      	#   input :play => ["if-this-is-correct-press", 1, "otherwise-press", 2]
+      	#
+      	# When specifying files to play, the playback of the sequence of files will stop
+      	# immediately when the user presses the first digit.
+      	#
+      	# The :timeout option works like a digit timeout, therefore each digit pressed
+      	# causes the timer to reset. This is a much more user-friendly approach than an
+        # absolute timeout.
+      	#
+        # Note that when the digit limit is not specified the :accept_key becomes "#".
+        # Otherwise there would be no way to end the collection of digits. You can
+      	# obviously override this by passing in a new key with :accept_key.
+        def input(*args)
+          options = args.last.kind_of?(Hash) ? args.pop : {}
+          number_of_digits = args.shift
+
+          sound_files     = Array options.delete(:play)
+          timeout         = options.delete(:timeout)
+          terminating_key = options.delete(:accept_key)
+          terminating_key = if terminating_key
+            terminating_key.to_s
+          elsif number_of_digits.nil? && !terminating_key.equal?(false)
+            '#'
+          end
+
+          if number_of_digits && number_of_digits < 0
+            ahn_log.agi.warn "Giving -1 to input() is now deprecated. Don't specify a first " +
+                             "argument to simulate unlimited digits." if number_of_digits == -1
+            raise ArgumentError, "The number of digits must be positive!"
+          end
+
+          buffer = ''
+          key = sound_files.any? ? interruptible_play(*sound_files) || '' : wait_for_digit(timeout || -1)
+          loop do
+            return buffer if key.nil?
+            if terminating_key
+              if key == terminating_key
+                return buffer
+              else
+                buffer << key
+                return buffer if number_of_digits && number_of_digits == buffer.length
+              end
+            else
+              buffer << key
+              return buffer if number_of_digits && number_of_digits == buffer.length
+            end
+            key = wait_for_digit(timeout || -1)
+          end
+      	end
+
+        # 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.
+        #
+        # You can optionally override certain dialplan variables when jumping to the context. A popular use of
+        # this is to redefine +extension+ (which this method automatically boxes with a PhoneNumber object) so
+        # you can effectively "restart" a call (from the perspective of the jumped-to context). When you override
+        # variables here, you're effectively blowing away the old variables. If you need them for some reason,
+        # you should assign the important ones to an instance variable first before calling this method.
+        def jump_to(context, overrides={})
+          context = lookup_context_with_name(context) if context.kind_of?(Symbol) || (context.kind_of?(String) && context =~ /^[\w_]+$/)
+
+          # JRuby has a bug that prevents us from correctly determining the class name.
+          # See: http://jira.codehaus.org/browse/JRUBY-5026
+          if !(context.kind_of?(Adhearsion::DialPlan::DialplanContextProc) || context.kind_of?(Proc))
+            raise Adhearsion::VoIP::DSL::Dialplan::ContextNotFoundException
+          end
+
+          if overrides.any?
+            overrides = overrides.symbolize_keys
+            if overrides.has_key?(:extension) && !overrides[:extension].kind_of?(Adhearsion::VoIP::DSL::PhoneNumber)
+              overrides[:extension] = Adhearsion::VoIP::DSL::PhoneNumber.new overrides[:extension]
+            end
+
+            overrides.each_pair do |key, value|
+              meta_def(key) { value }
+            end
+          end
+
+          raise Adhearsion::VoIP::DSL::Dialplan::ControlPassingException.new(context)
+        end
+
+      	# Place a call in a queue to be answered by a registered agent. You must then call join!()
+      	#
+      	# @param [String] queue_name the queue name to place the caller in
+      	# @return [Adhearsion::VoIP::Asterisk::Commands::QueueProxy] a queue proxy object
+        #
+        # @see http://www.voip-info.org/wiki-Asterisk+cmd+Queue Full information on the Asterisk Queue
+        # @see Adhearsion::VoIP::Asterisk::Commands::QueueProxy#join! join!() for further details
+      	def queue(queue_name)
+      	  queue_name = queue_name.to_s
+
+      	  @queue_proxy_hash_lock = Mutex.new unless defined? @queue_proxy_hash_lock
+      	  @queue_proxy_hash_lock.synchronize do
+      	    @queue_proxy_hash ||= {}
+      	    if @queue_proxy_hash.has_key? queue_name
+        	    return @queue_proxy_hash[queue_name]
+      	    else
+      	      proxy = @queue_proxy_hash[queue_name] = QueueProxy.new(queue_name, self)
+      	      return proxy
+    	      end
+      	  end
+    	  end
+
+      	# Get the status of the last dial(). Possible dial statuses include :answer,
+        # :busy, :no_answer, :cancelled, :congested, and :channel_unavailable.
+        # If :cancel is returned, the caller hung up before the callee picked up.
+        # If :congestion is returned, the dialed extension probably doesn't exist.
+        # If :channel_unavailable, the callee phone may not be registered.
+      	def last_dial_status
+      	  DIAL_STATUSES[get_dial_status]
+      	end
+
+        # @return [Boolean] true if your last call to dial() finished with the ANSWER state,
+        # as reported by Asterisk. false otherwise
+        def last_dial_successful?
+          last_dial_status == :answered
+        end
+
+        # Opposite of last_dial_successful?()
+        def last_dial_unsuccessful?
+          not last_dial_successful?
+        end
+
+        # This feature is presently experimental! Do not use it!
+        def speak(text, engine=:none)
+          engine = AHN_CONFIG.asterisk.speech_engine || engine
+          execute SpeechEngines.send(engine, text)
+        end
+
+        # A high-level way of enabling features you create/uncomment from features.conf.
+        #
+        # Certain Symbol features you enable (as defined in DYNAMIC_FEATURE_EXTENSIONS) have optional
+        # arguments that you can also specify here. The usage examples show how to do this.
+        #
+        # Usage examples:
+        #
+        #   enable_feature :attended_transfer                        # Enables "atxfer"
+        #
+        #   enable_feature :attended_transfer, :context => "my_dial" # Enables "atxfer" and then
+        #                                                            # sets "TRANSFER_CONTEXT" to :context's value
+        #
+        #   enable_feature :blind_transfer, :context => 'my_dial'    # Enables 'blindxfer' and sets TRANSFER_CONTEXT
+        #
+        #   enable_feature "foobar"                                  # Enables "foobar"
+        #
+        #   enable_feature("dup"); enable_feature("dup")             # Enables "dup" only once.
+        def enable_feature(feature_name, optional_options=nil)
+          if DYNAMIC_FEATURE_EXTENSIONS.has_key? feature_name
+            instance_exec(optional_options, &DYNAMIC_FEATURE_EXTENSIONS[feature_name])
+          else
+            raise ArgumentError, "You cannot supply optional options when the feature name is " +
+                                 "not internally recognized!" if optional_options
+            extend_dynamic_features_with feature_name
+          end
+        end
+
+        # Disables a feature name specified in features.conf. If you're disabling it, it was probably
+        # set by enable_feature().
+        #
+        # @param [String] feature_name
+        def disable_feature(feature_name)
+          enabled_features_variable = variable 'DYNAMIC_FEATURES'
+          enabled_features = enabled_features_variable.split('#')
+          if enabled_features.include? feature_name
+            enabled_features.delete feature_name
+            variable 'DYNAMIC_FEATURES' => enabled_features.join('#')
+          end
+        end
+
+        # 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.
+        #
+        # @param [String] conference_id
+        # @param [Hash] options
+        #
+        # @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
+          pin = options[:pin]
+          raise ArgumentError, "A conference PIN number must be numerical!" if pin && pin.to_s !~ /^\d+$/
+
+          # To disable dynamic conference creation set :use_static_conf => true
+          use_static_conf = options.has_key?(:use_static_conf) ? options[:use_static_conf] : false
+
+          # The 'd' option of MeetMe creates conferences dynamically.
+          command_flags += 'd' unless (command_flags.include?('d') or use_static_conf)
+
+          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)
+        # Use get_variable to pass information from other modules or high level configurations from the asterisk dialplan
+        # to the adhearsion dialplan.
+        #
+        # @param [String] variable_name
+        #
+        # @see: http://www.voip-info.org/wiki/view/get+variable Asterisk Get Variable
+      	def get_variable(variable_name)
+      	  result = response("GET VARIABLE", variable_name)
+      	  case result
+      	    when "200 result=0"
+      	      return nil
+    	    when /^200 result=1 \((.*)\)$/
+    	      return $LAST_PAREN_MATCH
+    	    end
+    	  end
+
+    	  # Pass information back to the asterisk dial plan.
+    	  #
+    	  # 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.
+    	  #
+    	  # @param [String] variable_name
+    	  # @param [String] value
+    	  #
+    	  # @see http://www.voip-info.org/wiki/view/set+variable Asterisk Set Variable
+    	  def set_variable(variable_name, value)
+    	    response("SET VARIABLE", variable_name, value) == "200 result=1"
+  	    end
+        
+        # Issue the command to add a custom SIP header to the current call channel
+        # example use: sip_add_header("x-ahn-test", "rubyrox")
+        #
+        # @param[String] the name of the SIP header
+        # @param[String] the value of the SIP header
+        # 
+        # @return [String] the Asterisk response
+        #
+        # @see http://www.voip-info.org/wiki/index.php?page=Asterisk+cmd+SIPAddHeader Asterisk SIPAddHeader
+        def sip_add_header(header, value)
+          execute("SIPAddHeader", "#{header}: #{value}") == "200 result=1"
+        end
+        
+        # Issue the command to fetch a SIP header from the current call channel
+        # example use: sip_get_header("x-ahn-test")
+        #
+        # @param[String] the name of the SIP header to get
+        # 
+        # @return [String] the Asterisk response
+        #
+        # @see http://www.voip-info.org/wiki/index.php?page=Asterisk+cmd+SIPGetHeader Asterisk SIPGetHeader
+        def sip_get_header(header)
+          get_variable("SIP_HEADER(#{header})")
+        end
+        alias :sip_header :sip_get_header
+        
+    	  # 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
+      	    raise ArgumentError, "Can't mix variable setting and fetching!" if args.any?
+      	    assignments.each_pair do |key, value|
+      	      set_variable(key, value)
+    	      end
+    	    else
+    	      if args.size == 1
+    	        get_variable args.first
+  	        else
+      	      args.map { |var| get_variable(var) }
+    	      end
+    	    end
+  	    end
+
+    	  # Send a caller to a voicemail box to leave a message.
+    	  #
+    	  # 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.
+    	  #
+    	  # @see http://www.voip-info.org/tiki-index.php?page=Asterisk+cmd+VoiceMail Asterisk Voicemail
+        def voicemail(*args)
+          options_hash    = args.last.kind_of?(Hash) ? args.pop : {}
+          mailbox_number  = args.shift
+          greeting_option = options_hash.delete(:greeting)
+          skip_option     = options_hash.delete(:skip)
+          raise ArgumentError, 'You supplied too many arguments!' if mailbox_number && options_hash.any?
+          greeting_option = case greeting_option
+            when :busy then 'b'
+            when :unavailable then 'u'
+            when nil then nil
+            else raise ArgumentError, "Unrecognized greeting #{greeting_option}"
+          end
+          skip_option &&= 's'
+          options = "#{greeting_option}#{skip_option}"
+
+          raise ArgumentError, "Mailbox cannot be blank!" if !mailbox_number.nil? && mailbox_number.blank?
+          number_with_context = if mailbox_number then mailbox_number else
+            raise ArgumentError, "You must supply ONE context name!" if options_hash.size != 1
+            context_name, mailboxes = options_hash.to_a.first
+            Array(mailboxes).map do |mailbox|
+              raise ArgumentError, "Mailbox numbers must be numerical!" unless mailbox.to_s =~ /^\d+$/
+              "#{mailbox}@#{context_name}"
+            end.join('&')
+          end
+          execute('voicemail', number_with_context, options)
+          case variable('VMSTATUS')
+            when 'SUCCESS' then true
+            when 'USEREXIT' then false
+            else nil
+          end
+        end
+
+        # The voicemail_main method puts a caller into the voicemail system to fetch their voicemail
+        # or set options for their voicemail box.
+        #
+        # @param [Hash] options
+        #
+        # @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
+
+          folder = if folder
+            if folder.to_s =~ /^[\w_]+$/
+              "a(#{folder})"
+            else
+              raise ArgumentError, "Voicemail folder must be alphanumerical/underscore characters only!"
+            end
+          elsif folder == ''
+            raise "Folder name cannot be an empty String!"
+          else
+            nil
+          end
+
+          real_mailbox = ""
+          real_mailbox << "#{mailbox}"  unless mailbox.blank?
+          real_mailbox << "@#{context}" unless context.blank?
+
+          real_options = ""
+          real_options << "s" if !authenticate
+          real_options << folder unless folder.blank?
+
+          command_args = [real_mailbox]
+          command_args << real_options unless real_options.blank?
+          command_args.clear if command_args == [""]
+
+          execute 'VoiceMailMain', *command_args
+        end
+
+        def check_voicemail
+          ahn_log.agi.warn "THE check_voicemail() DIALPLAN METHOD WILL SOON BE DEPRECATED! CHANGE THIS TO voicemail_main() INSTEAD"
+          voicemail_main
+        end
+
+        # Dial an extension or "phone number" in asterisk.
+        # Maps to the Asterisk DIAL command in the asterisk dialplan.
+        #
+        # @param [String] number 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.
+        #
+        # @param [Hash] options
+        #
+        # +: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 check the link below.
+        #
+        # +: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
+
+          unrecognized_options = options.keys - recognized_options
+          raise ArgumentError, "Unknown dial options: #{unrecognized_options.to_sentence}" if unrecognized_options.any?
+          set_caller_id_name options[:name]
+          set_caller_id_number options[:caller_id]
+          confirm_option = dial_macro_option_compiler options[:confirm]
+          all_options = options[:options]
+          all_options = all_options ? all_options + confirm_option : confirm_option
+          execute "Dial", number, options[:for], all_options
+        end
+
+
+        # This implementation of dial() uses the experimental call routing DSL.
+        #
+        # def dial(number, options={})
+        #   rules = callable_routes_for number
+        #   return :no_route if rules.empty?
+        #   call_attempt_status = nil
+        #   rules.each do |provider|
+        #
+        #     response = execute "Dial",
+        #       provider.format_number_for_platform(number),
+        #       timeout_from_dial_options(options),
+        #       asterisk_options_from_dial_options(options)
+        #
+        #     call_attempt_status = last_dial_status
+        #     break if call_attempt_status == :answered
+        #   end
+        #   call_attempt_status
+        # end
+
+
+      	# Speaks the digits given as an argument. For example, "123" is spoken as "one two three".
+      	#
+      	# @param [String] digits
+      	def say_digits(digits)
+      	  execute "saydigits", validate_digits(digits)
+      	end
+
+      	# Get the number of seconds the given block takes to execute. This
+      	# is particularly useful in dialplans for tracking billable time. Note that
+      	# if the call is hung up during the block, you will need to rescue the
+      	# exception if you have some mission-critical logic after it with which
+      	# you're recording this return-value.
+      	#
+      	# @return [Float] number of seconds taken for block to execute
+        def duration_of
+          start_time = Time.now
+          yield
+          Time.now - start_time
+        end
+
+        #
+        # Play a sequence of files, stopping the playback if a digit is pressed.
+        #
+        # @return [String, nil] digit pressed, or nil if none
+        #
+        def interruptible_play(*files)
+          files.flatten.each do |file|
+            result = result_digit_from response("STREAM FILE", file, "1234567890*#")
+            return result if result != 0.chr
+          end
+          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
+          def wait_for_digit(timeout=-1)
+            timeout *= 1_000 if timeout != -1
+            result = result_digit_from 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)
+            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
+
+          # allows setting of the callerid number of the call
+          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
+          def set_caller_id_name(caller_id_name)
+            return unless caller_id_name
+            variable "CALLERID(name)" => caller_id_name
+          end
+
+          def timeout_from_dial_options(options)
+            options[:for] || options[:timeout]
+          end
+
+          def asterisk_options_from_dial_options(options)
+            # TODO: Will become much more sophisticated soon to handle callerid, etc
+            options[:options]
+          end
+
+          def dial_macro_option_compiler(confirm_argument_value)
+            defaults = { :macro => 'ahn_dial_confirmer',
+                         :timeout => 20.seconds,
+                         :play => "beep",
+                         :key => '#' }
+
+            case confirm_argument_value
+              when true
+                DialPlan::ConfirmationManager.encode_hash_for_dial_macro_argument(defaults)
+              when false, nil
+                ''
+              when Proc
+                raise NotImplementedError, "Coming in the future, you can do :confirm => my_context."
+
+              when Hash
+                options = defaults.merge confirm_argument_value
+                if((confirm_argument_value.keys - defaults.keys).any?)
+                  raise ArgumentError, "Known options: #{defaults.keys.to_sentence}"
+                end
+                raise ArgumentError, "Bad macro name!" unless options[:macro].to_s =~ /^[\w_]+$/
+                options[:timeout] = case options[:timeout]
+                  when Fixnum, ActiveSupport::Duration
+                    options[:timeout]
+                  when String
+                    raise ArgumentError, "Timeout must be numerical!" unless options[:timeout] =~ /^\d+$/
+                    options[:timeout].to_i
+                  when :none
+                    0
+                  else
+                    raise ArgumentError, "Unrecognized :timeout! #{options[:timeout].inspect}"
+                end
+                raise ArgumentError, "Unrecognized DTMF key: #{options[:key]}" unless options[:key].to_s =~ /^[\d#*]$/
+                options[:play] = Array(options[:play]).join('++')
+                DialPlan::ConfirmationManager.encode_hash_for_dial_macro_argument options
+
+              else
+                raise ArgumentError, "Unrecognized :confirm option: #{confirm_argument_value.inspect}!"
+            end
+          end
+
+          def result_digit_from(response_string)
+            raise ArgumentError, "Can't coerce nil into AGI response! This could be a bug!" unless response_string
+            digit = response_string[/^#{response_prefix}(-?\d+(\.\d+)?)/,1]
+            digit.to_i.chr if digit && digit.to_s != "-1"
+          end
+
+          def extract_input_from(result)
+            return false if error?(result)
+            # return false if input_timed_out?(result)
+
+            # This regexp doesn't match if there was a timeout with no
+            # inputted digits, therefore returning nil.
+
+            result[/^#{response_prefix}([\d*]+)/, 1]
+          end
+
+          def extract_variable_from(result)
+            return false if error?(result)
+            result[/^#{response_prefix}1 \((.+)\)/, 1]
+          end
+
+          def get_dial_status
+            dial_status = variable('DIALSTATUS')
+            dial_status ? dial_status.downcase.to_sym : :cancelled
+          end
+
+
+          def play_numeric(argument)
+            if argument.kind_of?(Numeric) || argument =~ /^\d+$/
+              execute(:saynumber, argument)
+            end
+          end
+
+          def play_string(argument)
+            execute(:playback, argument)
+          end
+
+          def play_sound_files_for_menu(menu_instance, sound_files)
+            digit = nil
+            if sound_files.any? && menu_instance.digit_buffer_empty?
+              digit = interruptible_play(*sound_files)
+            end
+            digit || wait_for_digit(menu_instance.timeout)
+          end
+
+          def extend_dynamic_features_with(feature_name)
+            current_variable = variable("DYNAMIC_FEATURES") || ''
+            enabled_features = current_variable.split '#'
+            unless enabled_features.include? feature_name
+              enabled_features << feature_name
+              variable "DYNAMIC_FEATURES" => enabled_features.join('#')
+            end
+          end
+
+          def jump_to_context_with_name(context_name)
+            context_lambda = lookup_context_with_name context_name
+            raise Adhearsion::VoIP::DSL::Dialplan::ControlPassingException.new(context_lambda)
+          end
+
+          def lookup_context_with_name(context_name)
+            begin
+              send context_name
+            rescue NameError
+              raise Adhearsion::VoIP::DSL::Dialplan::ContextNotFoundException
+            end
+          end
+
+          def redefine_extension_to_be(new_extension)
+            new_extension = Adhearsion::VoIP::DSL::PhoneNumber.new new_extension
+            meta_def(:extension) { new_extension }
+          end
+
+          def to_pbx
+            io
+          end
+
+          def from_pbx
+            io
+          end
+
+          def validate_digits(digits)
+            digits.to_s.tap do |digits_as_string|
+              raise ArgumentError, "Can only be called with valid digits!" unless digits_as_string =~ /^[0-9*#-]+$/
+            end
+          end
+
+          def error?(result)
+            result.to_s[/^#{response_prefix}(?:-\d+)/]
+          end
+
+          # timeout with pressed digits:    200 result=<digits> (timeout)
+          # timeout without pressed digits: 200 result= (timeout)
+          # @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
+
+          def io
+            call.io
+          end
+
+          def response_prefix
+            RESPONSE_PREFIX
+          end
+
+          class QueueProxy
+
+            class << self
+
+              def format_join_hash_key_arguments(options)
+
+                bad_argument = lambda do |(key, value)|
+                  raise ArgumentError, "Unrecognize value for #{key.inspect} -- #{value.inspect}"
+                end
+
+                # Direct Queue() arguments:
+                timeout        = options.delete :timeout
+                announcement   = options.delete :announce
+
+                # Terse single-character options
+                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?
+
+                ring_style = case ring_style
+                  when :ringing then 'r'
+                  when :music then   ''
+                  when nil
+                  else bad_argument[:play => ring_style]
+                end.to_s
+
+                allow_hangup = case allow_hangup
+                  when :caller then   'H'
+                  when :agent then    'h'
+                  when :everyone then 'Hh'
+                  when nil
+                  else bad_argument[:allow_hangup => allow_hangup]
+                end.to_s
+
+                allow_transfer = case allow_transfer
+                  when :caller then   'T'
+                  when :agent then    't'
+                  when :everyone then 'Tt'
+                  when nil
+                  else bad_argument[:allow_transfer => allow_transfer]
+                end.to_s
+
+                terse_character_options = ring_style + allow_transfer + allow_hangup
+
+                [terse_character_options, '', announcement, timeout, agi].map(&:to_s)
+              end
+
+            end
+
+            attr_reader :name, :environment
+            def initialize(name, environment)
+              @name, @environment = name, environment
+            end
+
+            # Makes the current channel join the queue.
+            #
+            # @param [Hash] options
+            #
+            #   :timeout        - The number of seconds to wait for an agent to answer
+            #   :play           - Can be :ringing or :music.
+            #   :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!
+            #  @example
+            #    queue('sales').join! :timeout => 1.minute
+            #  @example
+            #    queue('sales').join! :play => :music
+            #  @example
+            #    queue('sales').join! :play => :ringing
+            #  @example
+            #    queue('sales').join! :announce => "custom/special-queue-announcement"
+            #  @example
+            #    queue('sales').join! :allow_transfer => :caller
+            #  @example
+            #    queue('sales').join! :allow_transfer => :agent
+            #  @example
+            #    queue('sales').join! :allow_hangup   => :caller
+            #  @example
+            #    queue('sales').join! :allow_hangup   => :agent
+            #  @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))
+          	  normalize_queue_status_variable environment.variable("QUEUESTATUS")
+            end
+
+            # Get the agents associated with a queue
+            #
+            # @param [Hash] options
+            # @return [QueueAgentsListProxy]
+            def agents(options={})
+              cached = options.has_key?(:cache) ? options.delete(:cache) : true
+              raise ArgumentError, "Unrecognized arguments to agents(): #{options.inspect}" if options.keys.any?
+              if cached
+                @cached_proxy ||= QueueAgentsListProxy.new(self, true)
+              else
+                @uncached_proxy ||=  QueueAgentsListProxy.new(self, false)
+              end
+            end
+
+            # Check how many channels are waiting in the queue
+            # @return [Integer]
+            # @raise QueueDoesNotExistError
+            def waiting_count
+              raise QueueDoesNotExistError.new(name) unless exists?
+              environment.variable("QUEUE_WAITING_COUNT(#{name})").to_i
+            end
+
+            # Check whether the waiting count is zero
+            # @return [Boolean]
+            def empty?
+              waiting_count == 0
+            end
+
+            # Check whether any calls are waiting in the queue
+            # @return [Boolean]
+            def any?
+              waiting_count > 0
+            end
+
+            # Check whether a queue exists/is defined in Asterisk
+            # @return [Boolean]
+            def exists?
+              environment.execute('RemoveQueueMember', name, 'SIP/AdhearsionQueueExistenceCheck')
+              environment.variable("RQMSTATUS") != 'NOSUCHQUEUE'
+            end
+
+            private
+
+            # Ensure the queue exists by interpreting the QUEUESTATUS variable
+            #
+            # 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
+            # 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 = "COMPLETED" if variable.nil?
+              variable.downcase.to_sym
+            end
+
+            class QueueAgentsListProxy
+
+              include Enumerable
+
+              attr_reader :proxy, :agents
+              def initialize(proxy, cached=false)
+                @proxy  = proxy
+                @cached = cached
+              end
+
+              def count
+                if cached? && @cached_count
+                  @cached_count
+                else
+                  @cached_count = proxy.environment.variable("QUEUE_MEMBER_COUNT(#{proxy.name})").to_i
+                end
+              end
+              alias size count
+              alias length count
+
+              # @param [Hash] args
+              # :name value will be viewable in the queue_log
+              # :penalty is the penalty assigned to this agent for answering calls on this queue
+              def new(*args)
+
+                options   = args.last.kind_of?(Hash) ? args.pop : {}
+                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)               || ''
+                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, state_interface)
+
+                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
+
+                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
+              # the message which says "Agent logged in".
+              def login!(*args)
+                options = args.last.kind_of?(Hash) ? args.pop : {}
+
+                silent = options.delete(:silent).equal?(false) ? '' : 's'
+                id     = args.shift
+                id   &&= AgentProxy.id_from_agent_channel(id)
+                raise ArgumentError, "Unrecognized Hash options to login(): #{options.inspect}" if options.any?
+                raise ArgumentError, "Unrecognized argument to login(): #{args.inspect}" if args.any?
+
+                proxy.environment.execute('AgentLogin', id, silent)
+              end
+
+              # Removes the current channel from this queue
+              def logout!
+                # TODO: DRY this up. Repeated in the AgentProxy...
+                proxy.environment.execute 'RemoveQueueMember', proxy.name
+                case proxy.environment.variable("RQMSTATUS")
+                  when "REMOVED"     then true
+                  when "NOTINQUEUE"  then false
+                  when "NOSUCHQUEUE"
+                    raise QueueDoesNotExistError.new(proxy.name)
+                  else
+                    raise "Unrecognized RQMSTATUS variable!"
+                end
+              end
+
+              def each(&block)
+                check_agent_cache!
+                agents.each(&block)
+              end
+
+              def first
+                check_agent_cache!
+                agents.first
+              end
+
+              def last
+                check_agent_cache!
+                agents.last
+              end
+
+              def cached?
+                @cached
+              end
+
+              def to_a
+                check_agent_cache!
+                @agents
+              end
+
+              private
+
+              def check_agent_cache!
+                if cached?
+                  load_agents! unless agents
+                else
+                  load_agents!
+                end
+              end
+
+              def load_agents!
+                raw_data = proxy.environment.variable "QUEUE_MEMBER_LIST(#{proxy.name})"
+                @agents = raw_data.split(',').map(&:strip).reject(&:empty?).map do |agent|
+                  AgentProxy.new(agent, proxy)
+                end
+                @cached_count = @agents.size
+              end
+
+            end
+
+            class AgentProxy
+
+              SUPPORTED_METADATA_NAMES = %w[status password name mohclass exten channel] unless defined? SUPPORTED_METADATA_NAMES
+
+              class << self
+                def id_from_agent_channel(id)
+                  id = id.to_s
+                  id.starts_with?('Agent/') ? id[%r[^Agent/(.+)$],1] : id
+                end
+              end
+
+              attr_reader :interface, :proxy, :queue_name, :id
+              def initialize(interface, proxy)
+                @interface  = interface
+                @id         = self.class.id_from_agent_channel interface
+                @proxy      = proxy
+                @queue_name = proxy.name
+              end
+
+              def remove!
+                proxy.environment.execute 'RemoveQueueMember', queue_name, interface
+                case proxy.environment.variable("RQMSTATUS")
+                  when "REMOVED"     then true
+                  when "NOTINQUEUE"  then false
+                  when "NOSUCHQUEUE"
+                    raise QueueDoesNotExistError.new(queue_name)
+                  else
+                    raise "Unrecognized RQMSTATUS variable!"
+                end
+              end
+
+              # Pauses the given agent for this queue only. If you wish to pause this agent
+              # for all queues, pass in :everywhere => true. Returns true if the agent was
+              # successfully paused and false if the agent was not found.
+              def pause!(options={})
+                everywhere = options.delete(:everywhere)
+                args = [(everywhere ? nil : queue_name), interface]
+                proxy.environment.execute('PauseQueueMember', *args)
+                case proxy.environment.variable("PQMSTATUS")
+                  when "PAUSED"   then true
+                  when "NOTFOUND" then false
+                  else
+                    raise "Unrecognized PQMSTATUS value!"
+                end
+              end
+
+              # Pauses the given agent for this queue only. If you wish to pause this agent
+              # for all queues, pass in :everywhere => true. Returns true if the agent was
+              # successfully paused and false if the agent was not found.
+              def unpause!(options={})
+                everywhere = options.delete(:everywhere)
+                args = [(everywhere ? nil : queue_name), interface]
+                proxy.environment.execute('UnpauseQueueMember', *args)
+                case proxy.environment.variable("UPQMSTATUS")
+                  when "UNPAUSED" then true
+                  when "NOTFOUND" then false
+                  else
+                    raise "Unrecognized UPQMSTATUS value!"
+                end
+              end
+
+              # Returns true/false depending on whether this agent is logged in.
+              def logged_in?
+                status == 'LOGGEDIN'
+              end
+
+              private
+
+              def status
+                agent_metadata 'status'
+              end
+
+              def agent_metadata(data_name)
+                data_name = data_name.to_s.downcase
+                raise ArgumentError, "unrecognized agent metadata name #{data_name}" unless SUPPORTED_METADATA_NAMES.include? data_name
+                proxy.environment.variable "AGENT(#{id}:#{data_name})"
+              end
+
+            end
+
+            class QueueDoesNotExistError < StandardError
+              def initialize(queue_name)
+                super "Queue #{queue_name} does not exist!"
+              end
+            end
+
+          end
+
+          module MenuDigitResponse
+            def timed_out?
+              eql? 0.chr
+            end
+          end
+
+          module SpeechEngines
+
+            class InvalidSpeechEngine < StandardError; end
+
+            class << self
+              def cepstral(text)
+                puts "in ceptral"
+                puts escape(text)
+              end
+
+              def festival(text)
+                raise NotImplementedError
+              end
+
+              def none(text)
+                raise InvalidSpeechEngine, "No speech engine selected. You must specify one in your Adhearsion config file."
+              end
+
+              def method_missing(engine_name, text)
+                raise InvalidSpeechEngine, "Unsupported speech engine #{engine_name} for speaking '#{text}'"
+              end
+
+              private
+
+              def escape(text)
+                "%p" % text
+              end
+
+            end
+          end
+
+      end
+    end
+  end
+end