kenwiesner-adhearsioncw 0.8.3

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

@@ -0,0 +1,597 @@
+require 'adhearsion/voip/asterisk/manager_interface/ami_lexer'
+
+module Adhearsion
+  module VoIP
+    module Asterisk
+      
+      ##
+      # Sorry, this AMI class has been deprecated. Please see http://docs.adhearsion.com/Asterisk_Manager_Interface for
+      # documentation on the new way of handling AMI. This new version is much better and should not require an enormous
+      # migration on your part.
+      #
+      class AMI
+        def initialize
+          raise "Sorry, this AMI class has been deprecated. Please see http://docs.adhearsion.com/Asterisk_Manager_Interface for documentation on the new way of handling AMI. This new version is much better and should not require an enormous migration on your part."
+        end
+      end
+      
+      mattr_accessor :manager_interface
+      
+      module Manager
+        
+        ##
+        # This class abstracts a connection to the Asterisk Manager Interface. Its purpose is, first and foremost, to make
+        # the protocol consistent. Though the classes employed to assist this class (ManagerInterfaceAction,
+        # ManagerInterfaceResponse, ManagerInterfaceError, etc.) are relatively user-friendly, they're designed to be a
+        # building block on which to build higher-level abstractions of the Asterisk Manager Interface.
+        #
+        # For a higher-level abstraction of the Asterisk Manager Interface, see the SuperManager class.
+        #
+        class ManagerInterface
+          
+          class << self
+            
+            def connect(*args)
+              returning new(*args) do |connection|
+                connection.connect!
+              end
+            end
+            
+            def replies_with_action_id?(name, headers={})
+              name = name.to_s.downcase
+              # TODO: Expand this case statement
+              case name
+                when "queues", "iaxpeers"
+                  false
+                else
+                  true
+              end                
+            end
+            
+            ##
+            # When sending an action with "causal events" (i.e. events which must be collected to form a proper
+            # response), AMI should send a particular event which instructs us that no more events will be sent.
+            # This event is called the "causal event terminator".
+            #
+            # Note: you must supply both the name of the event and any headers because it's possible that some uses of an 
+            # action (i.e. same name, different headers) have causal events while other uses don't.
+            #
+            # @param [String] name the name of the event
+            # @param [Hash] the headers associated with this event
+            # @return [String] the downcase()'d name of the event name for which to wait
+            #
+            def has_causal_events?(name, headers={})
+              name = name.to_s.downcase
+              case name
+                when "queuestatus", "sippeers", "parkedcalls", "status"
+                  true
+                else
+                  false
+              end
+            end
+            
+            ##
+            # Used to determine the event name for an action which has causal events.
+            # 
+            # @param [String] action_name
+            # @return [String] The corresponding event name which signals the completion of the causal event sequence.
+            # 
+            def causal_event_terminator_name_for(action_name)
+              return nil unless has_causal_events?(action_name)
+              action_name = action_name.to_s.downcase 
+               case action_name
+                 when "queuestatus", 'parkedcalls', "status"
+                   action_name + "complete"
+                 when "sippeers"
+                   "peerlistcomplete"
+               end
+            end
+            
+          end
+        
+          DEFAULT_SETTINGS = {
+            :host     => "localhost",
+            :port     => 5038,
+            :username => "admin",
+            :password => "secret",
+            :events   => true
+          }.freeze unless defined? DEFAULT_SETTINGS
+          
+          attr_reader *DEFAULT_SETTINGS.keys
+          
+          ##
+          # Creates a new Asterisk Manager Interface connection and exposes certain methods to control it. The constructor
+          # takes named parameters as Symbols. Note: if the :events option is given, this library will establish a separate
+          # socket for just events. Two sockets are used because some actions actually respond with events, making it very
+          # complicated to differentiate between response-type events and normal events.
+          #
+          # @param [Hash] options Available options are :host, :port, :username, :password, and :events
+          #
+          def initialize(options={})
+            options = parse_options options
+            
+            @host = options[:host]
+            @username = options[:username] 
+            @password = options[:password]
+            @port     = options[:port]
+            @events   = options[:events]
+            
+            @sent_messages = {}
+            @sent_messages_lock = Mutex.new
+            
+            @actions_lexer = DelegatingAsteriskManagerInterfaceLexer.new self, \
+                :message_received => :action_message_received,
+                :error_received   => :action_error_received
+            
+            @write_queue = Queue.new
+            
+            if @events
+              @events_lexer = DelegatingAsteriskManagerInterfaceLexer.new self, \
+                  :message_received => :event_message_received,
+                  :error_received   => :event_error_received 
+            end
+          end
+          
+          def action_message_received(message)
+            if message.kind_of? Manager::ManagerInterfaceEvent
+              # Trigger the return value of the waiting action id...
+              corresponding_action   = @current_action_with_causal_events
+              event_collection       = @event_collection_for_current_action
+              
+              if corresponding_action
+                
+                # If this is the meta-event which signals no more events will follow and the response is complete.
+                if message.name.downcase == corresponding_action.causal_event_terminator_name
+                  
+                  # Result found! Wake up any Threads waiting
+                  corresponding_action.future_resource.resource = event_collection.freeze
+                  
+                  @current_action_with_causal_events   = nil
+                  @event_collection_for_current_action = nil
+                  
+                else
+                  event_collection << message
+                  # We have more causal events coming.
+                end
+              else
+                ahn_log.ami.error "Got an unexpected event on actions socket! This may be a bug! #{message.inspect}"
+              end
+              
+            elsif message["ActionID"].nil?
+              # No ActionID! Release the write lock and wake up the waiter
+            else
+              action_id = message["ActionID"]
+              corresponding_action = data_for_message_received_with_action_id action_id
+              if corresponding_action
+                message.action = corresponding_action
+                
+                if corresponding_action.has_causal_events?
+                  # By this point the write loop will already have started blocking by calling the response() method on the
+                  # action. Because we must collect more events before we wake the write loop up again, let's create these
+                  # instance variable which will needed when the subsequent causal events come in.
+                  @current_action_with_causal_events   = corresponding_action
+                  @event_collection_for_current_action = []
+                else
+                  # Wake any Threads waiting on the response.
+                  corresponding_action.future_resource.resource = message
+                end
+              else
+                ahn_log.ami.error "Received an AMI message with an unrecognized ActionID!! This may be an bug! #{message.inspect}"
+              end
+            end
+          end
+          
+          def action_error_received(ami_error)
+            action_id = ami_error["ActionID"]
+            
+            corresponding_action = data_for_message_received_with_action_id action_id
+
+            if corresponding_action
+              corresponding_action.future_resource.resource = ami_error
+            else
+              ahn_log.ami.error "Received an AMI error with an unrecognized ActionID!! This may be an bug! #{ami_error.inspect}"
+            end
+          end
+          
+          ##
+          # Called only when this ManagerInterface is instantiated with events enabled.
+          #
+          def event_message_received(event)
+            return if event.kind_of?(ManagerInterfaceResponse) && event["Message"] == "Authentication accepted"
+            # TODO: convert the event name to a certain namespace.
+            Events.trigger %w[asterisk manager_interface], event
+          end
+          
+          def event_error_received(message)
+            # Does this ever even occur?
+            ahn_log.ami.error "Hmmm, got an error on the AMI events-only socket! This must be a bug! #{message.inspect}"
+          end
+          
+          ##
+          # Called when our Ragel parser encounters some unexpected syntax from Asterisk. Anytime this is called, it should
+          # be considered a bug in Adhearsion. Note: this same method is called regardless of whether the syntax error
+          # happened on the actions socket or on the events socket.
+          #
+          def syntax_error_encountered(ignored_chunk)
+            ahn_log.ami.error "ADHEARSION'S AMI PARSER ENCOUNTERED A SYNTAX ERROR! " + 
+                "PLEASE REPORT THIS ON http://bugs.adhearsion.com! OFFENDING TEXT:\n#{ignored_chunk.inspect}"
+          end
+          
+          ##
+          # Must be called after instantiation. Also see ManagerInterface::connect().
+          #
+          # @raise [AuthenticationFailedException] if username or password are rejected
+          #
+          def connect!
+            establish_actions_connection
+            establish_events_connection if @events
+            self
+          end
+          
+          def actions_connection_established
+            @actions_state = :connected
+            @actions_writer_thread = Thread.new(&method(:write_loop))
+          end
+          
+          def actions_connection_disconnected
+            @actions_state = :disconnected
+          end
+          
+          def events_connection_established
+            @events_state = :connected
+          end
+          
+          def actions_connection_disconnected
+            @events_state = :disconnected
+          end
+          
+          def disconnect!
+            # PSEUDO CODE
+            # TODO: Go through all the waiting condition variables and raise an exception
+            #@write_queue << :STOP!
+            raise NotImplementedError
+          end
+        
+          def dynamic
+            # TODO: Return an object which responds to method_missing
+          end
+                    
+          ##
+          # Used to directly send a new action to Asterisk. Note: NEVER supply an ActionID; these are handled internally.
+          #
+          # @param [String, Symbol] action_name The name of the action (e.g. Originate)
+          # @param [Hash] headers Other key/value pairs to send in this action. Note: don't provide an ActionID
+          # @return [FutureResource] Call resource() on this object if you wish to access the response (optional). Note: if the response has not come in yet, your Thread will wait until it does.
+          #
+          def send_action_asynchronously(action_name, headers={})
+            check_action_name action_name
+            action = ManagerInterfaceAction.new(action_name, headers)
+            if action.replies_with_action_id?
+              @write_queue << action
+              action
+            else
+              raise NotImplementedError
+            end
+          end
+          
+          ##
+          # Sends an action over the AMI connection and blocks your Thread until the response comes in. If there was an error
+          # for some reason, the error will be raised as an ManagerInterfaceError.
+          #
+          # @param [String, Symbol] action_name The name of the action (e.g. Originate)
+          # @param [Hash] headers Other key/value pairs to send in this action. Note: don't provide an ActionID
+          # @raise [ManagerInterfaceError] When Asterisk can't execute this action, it sends back an Error which is converted into an ManagerInterfaceError object and raised. Access ManagerInterfaceError#message for the reported message from Asterisk.
+          # @return [ManagerInterfaceResponse, ImmediateResponse] Contains the response from Asterisk and all headers
+          #
+          def send_action_synchronously(*args)
+            returning send_action_asynchronously(*args).response do |response|
+              raise response if response.kind_of?(ManagerInterfaceError)
+            end
+          end
+          
+          alias send_action send_action_synchronously
+        
+        
+          #######                                              #######
+          ###########                                      ###########
+          ################# SOON-DEPRECATED COMMANDS ################# 
+          ###########                                      ###########
+          #######                                              #######
+          
+          # ping sends an action to the Asterisk Manager Interface that returns a pong
+          # more details here: http://www.voip-info.org/wiki/index.php?page=Asterisk+Manager+API+Action+Ping
+          def ping
+            deprecation_warning
+            send_action "Ping"
+            true
+          end
+          
+          def deprecation_warning
+            ahn_log.ami.deprecation.warn "The implementation of the ping, originate, introduce, hangup, call_into_context " +
+                "and call_and_exec methods will soon be moved from this class to SuperManager. At the moment, the " +
+                "SuperManager abstractions are not completed. Don't worry. The migration to SuperManager will be very easy."+
+                " See http://docs.adhearsion.com/AMI for more information."
+          end
+          
+          # The originate method launches a call to Asterisk, full details here:
+          # http://www.voip-info.org/tiki-index.php?page=Asterisk+Manager+API+Action+Originate
+          # Takes these arguments as a hash:
+          #
+          #   Channel: Channel on which to originate the call (The same as you specify in the Dial application command)
+          #   Context: Context to use on connect (must use Exten & Priority with it)
+          #   Exten: Extension to use on connect (must use Context & Priority with it)
+          #   Priority: Priority to use on connect (must use Context & Exten with it)
+          #   Timeout: Timeout (in milliseconds) for the originating connection to happen(defaults to 30000 milliseconds)
+          #   CallerID: CallerID to use for the call
+          #   Variable: Channels variables to set (max 32). Variables will be set for both channels (local and connected).
+          #   Account: Account code for the call
+          #   Application: Application to use on connect (use Data for parameters)
+          #   Data : Data if Application parameter is used
+          #   Async: For the origination to be asynchronous (allows multiple calls to be generated without waiting for a response)
+          #   ActionID: The request identifier. It allows you to identify the response to this request. 
+          #   You may use a number or a string. Useful when you make several simultaneous requests.
+          #
+          # For example:
+          # originate { :channel  => 'SIP/1000@sipnetworks.com',
+          #             :context  => 'my_context',
+          #             :exten    => 's',
+          #             :priority => '1' }
+          def originate(options={})
+            deprecation_warning
+            options = options.clone
+            options[:callerid] = options.delete :caller_id if options.has_key? :caller_id
+            options[:exten] = options.delete :extension if options.has_key? :extension
+            send_action "Originate", options
+          end
+
+          # An introduction connects two endpoints together. The first argument is
+          # the first person the PBX will call. When she's picked up, Asterisk will
+          # play ringing while the second person is being dialed.
+          #
+          # The first argument is the person called first. Pass this as a canonical
+          # IAX2/server/user type argument. Destination takes the same format, but
+          # comma-separated Dial() arguments can be optionally passed after the
+          # technology.
+          #
+          # TODO: Provide an example when this works.
+          #
+          def introduce(caller, callee, opts={})
+            deprecation_warning
+            dial_args  = callee
+            dial_args += "|#{opts[:options]}" if opts[:options]
+            call_and_exec caller, "Dial", :args => dial_args, :caller_id => opts[:caller_id]
+          end
+
+          # hangup terminates a call accepts a channel as the argument
+          # full details here: http://www.voip-info.org/wiki/index.php?page=Asterisk+Manager+API+Action+Hangup
+          def hangup(channel)
+            deprecation_warning
+            send_action "Hangup", :channel => channel
+          end
+
+          # call_and_exec allows you to make a call to a channel and then execute an Astersik application
+          # on that call
+          def call_and_exec(channel, app, opts={})
+            deprecation_warning
+            args = { :channel => channel, :application => app }
+            args[:caller_id] = opts[:caller_id] if opts[:caller_id]
+            args[:data] = opts[:args] if opts[:args]
+            originate args
+          end
+
+          # call_into_context is syntactic sugar for the Asterisk originate command that allows you to 
+          # lanuch a call into a particular context. For example:
+          #
+          # call_into_context('SIP/1000@sipnetworks.com', 'my_context', { :variables => { :session_guid => new_guid }})
+          def call_into_context(channel, context, options={})
+            deprecation_warning
+            args = {:channel => channel, :context => context}
+            args[:priority] = options[:priority] || 1
+            args[:exten] = options[:extension] if options[:extension]
+            args[:caller_id] = options[:caller_id] if options[:caller_id]
+            if options[:variables] && options[:variables].kind_of?(Hash)
+              args[:variable] = options[:variables].map {|pair| pair.join('=')}.join('|')
+            end
+            originate args
+          end
+          
+          #######                                                  #######
+          ###########                                          ###########
+          ################# END SOON-DEPRECATED COMMANDS ################# 
+          ###########                                          ###########
+          #######                                                  #######
+
+        
+          protected
+          
+          ##
+          # This class will be removed once this AMI library fully supports all known protocol anomalies.
+          #
+          class UnsupportedActionName < ArgumentError
+            UNSUPPORTED_ACTION_NAMES = %w[
+              queues
+              iaxpeers
+            ] unless defined? UNSUPPORTED_ACTION_NAMES
+            def initialize(name)
+              super "At the moment this AMI library doesn't support the #{name.inspect} action because it causes a protocol anomaly. Support for it will be coming shortly."
+            end
+            
+          end
+          
+          def check_action_name(name)
+            name = name.to_s.downcase
+            raise UnsupportedActionName.new(name) if UnsupportedActionName::UNSUPPORTED_ACTION_NAMES.include? name
+            true
+          end
+          
+          def write_loop
+            loop do
+              next_action = @write_queue.shift
+              return :stopped if next_action.equal? :STOP!
+              register_action_with_metadata next_action
+              
+              ahn_log.ami.debug "Sending AMI action: #{"\n>>> " + next_action.to_s.gsub(/(\r\n)+/, "\n>>> ")}"
+              @actions_connection.send_data next_action.to_s
+              # If it's "causal event" action, we must wait here until it's fully responded
+              next_action.response if next_action.has_causal_events?
+            end
+          rescue => e
+            p e
+          end
+          
+          ##
+          # When we send out an AMI action, we need to track the ActionID and have the other Thread handling the socket IO
+          # notify the sending Thread that a response has been received. This method instantiates a new FutureResource and
+          # keeps it around in a synchronized Hash for the IO-handling Thread to notify when a response with a matching
+          # ActionID is seen again. See also data_for_message_received_with_action_id() which is how the IO-handling Thread
+          # gets the metadata registered in the method back later.
+          #
+          # @param [ManagerInterfaceAction] action The ManagerInterfaceAction to send
+          # @param [Hash] headers The other key/value pairs being sent with this message
+          #
+          def register_action_with_metadata(action)
+            raise ArgumentError, "Must supply an action!" if action.nil?
+            @sent_messages_lock.synchronize do
+              @sent_messages[action.action_id] = action
+            end
+          end
+          
+          def data_for_message_received_with_action_id(action_id)
+            @sent_messages_lock.synchronize do
+              @sent_messages.delete action_id
+            end
+          end
+          
+          ##
+          # Instantiates a new ManagerInterfaceActionsConnection and assigns it to @actions_connection.
+          #
+          # @return [EventSocket]
+          #
+          def establish_actions_connection
+            @actions_connection = EventSocket.connect(@host, @port) do |handler|
+              handler.receive_data { |data| @actions_lexer << data  }
+              handler.connected    { actions_connection_established  }
+              handler.disconnected { actions_connection_disconnected }
+            end
+            login_actions
+          end
+          
+          ##
+          # Instantiates a new ManagerInterfaceEventsConnection and assigns it to @events_connection.
+          #
+          # @return [EventSocket]
+          #
+          def establish_events_connection
+            
+            # Note: the @events_connection instance variable is set in login()
+            @events_connection = EventSocket.connect(@host, @port) do |handler|
+              handler.receive_data { |data| @events_lexer << data  }
+              handler.connected    { events_connection_established  }
+              handler.disconnected { events_connection_disconnected }
+            end
+            login_events
+            ahn_log.ami "Successful AMI events-only connection into #{@username}@#{@host}"
+          end
+
+          def login_actions
+            action = send_action_asynchronously "Login", "Username" => @username, "Secret" => @password, "Events" => "Off"
+            response = action.response
+            if response.kind_of? ManagerInterfaceError
+              raise AuthenticationFailedException, "Incorrect username and password! #{response.message}"
+            else
+              ahn_log.ami "Successful AMI actions-only connection into #{@username}@#{@host}"
+              response
+            end
+          end
+          
+          ##
+          # Since this method is always called after the login_actions method, an AuthenticationFailedException would have already
+          # been raised if the username/password were off. Because this is the only action we ever need to send on this socket,
+          # it goes straight to the EventSocket connection (bypassing the @write_queue).
+          #
+          def login_events
+            login_action = ManagerInterfaceAction.new "Login", "Username" => @username, "Secret" => @password, "Events" => "On"
+            @events_connection.send_data login_action.to_s
+          end
+          
+          def parse_options(options)
+            unrecognized_keys = options.keys.map { |key| key.to_sym } - DEFAULT_SETTINGS.keys
+            if unrecognized_keys.any?
+              raise ArgumentError, "Unrecognized named argument(s): #{unrecognized_keys.to_sentence}"
+            end
+            DEFAULT_SETTINGS.merge options
+          end
+          
+          ##
+          # Raised when calling ManagerInterface#connect!() and the server responds with an error after logging in.
+          #
+          class AuthenticationFailedException < Exception; end
+          
+          class NotConnectedError < Exception; end
+          
+          ##
+          # Each time ManagerInterface#send_action is invoked, a new ManagerInterfaceAction is instantiated.
+          #
+          class ManagerInterfaceAction
+            
+            attr_reader :name, :headers, :future_resource, :action_id, :causal_event_terminator_name
+            def initialize(name, headers={})
+              @name      = name.to_s.downcase.freeze
+              @headers   = headers.stringify_keys.freeze
+              @action_id = new_action_id.freeze
+              @future_resource = FutureResource.new
+              @causal_event_terminator_name = ManagerInterface.causal_event_terminator_name_for name
+            end
+            
+            ##
+            # Used internally by ManagerInterface for the actions in AMI which break the protocol's definition and do not
+            # reply with an ActionID.
+            #
+            def replies_with_action_id?
+              ManagerInterface.replies_with_action_id?(@name, @headers)
+            end
+            
+            ##
+            # Some AMI actions effectively respond with many events which collectively constitute the actual response. These
+            # Must be handled specially by the protocol parser, so this method helps inform the parser.
+            #
+            def has_causal_events?
+              ManagerInterface.has_causal_events?(@name, @headers)
+            end
+            
+            ##
+            # Abstracts the generation of new ActionIDs. This could be implemented virutally any way, provided each
+            # invocation returns something unique, so this will generate a GUID and return it.
+            #
+            # @return [String] characters in GUID format (e.g. "4C5F4E1C-A0F1-4D13-8751-C62F2F783062")
+            #
+            def new_action_id
+              new_guid # Implemented in lib/adhearsion/foundation/pseudo_guid.rb
+            end
+            
+            ##
+            # Converts this action into a protocol-valid String, ready to be sent over a socket.
+            #
+            def to_s
+              @textual_representation ||= (
+                  "Action: #{@name}\r\nActionID: #{@action_id}\r\n" +
+                  @headers.map { |(key,value)| "#{key}: #{value}" }.join("\r\n") +
+                  (@headers.any? ? "\r\n\r\n" : "\r\n")
+              )
+            end
+            
+            ##
+            # If the response has simply not been received yet from Asterisk, the calling Thread will block until it comes
+            # in. Once the response comes in, subsequent calls immediately return a reference to the ManagerInterfaceResponse
+            # object.
+            #
+            def response
+              future_resource.resource
+            end
+                        
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+module Adhearsion
+  class DialPlan
+    class ConfirmationManager
+      
+      class << self
+          
+        def encode_hash_for_dial_macro_argument(options)
+          options    = options.clone
+          macro_name = options.delete :macro
+          options[:play] &&= options[:play].kind_of?(Array) ? options[:play].join('++') : options[:play]
+          encoded_options = URI.escape options.map { |key,value| "#{key}:#{value}" }.join('!')
+          returning "M(#{macro_name}^#{encoded_options})" do |str|
+            if str.rindex('^') != str.index('^')
+              raise ArgumentError, "You seem to have supplied a :confirm option with a caret (^) in it!" + 
+                                   " Please remove it. This will blow Asterisk up."
+            end
+          end
+        end
+        
+        def handle(call)
+          new(call).handle
+        end
+        
+        def confirmation_call?(call)
+          call.variables.has_key?(:network_script) && call.variables[:network_script].starts_with?('confirm!')
+        end
+                
+        def decode_hash(encoded_hash)
+          encoded_hash = encoded_hash =~ /^M\((.+)\)$/ ? $1 : encoded_hash
+          encoded_hash = encoded_hash =~ /^([^:]+\^)?(.+)$/ ? $2 : encoded_hash # Remove the macro name if it's there
+          unencoded = URI.unescape(encoded_hash).split('!')
+          unencoded.shift unless unencoded.first.include?(':')
+          unencoded = unencoded.map { |pair| key, value = pair.split(':'); [key.to_sym ,value] }.flatten
+          returning Hash[*unencoded] do |hash|
+            hash[:timeout]    &&= hash[:timeout].to_i
+            hash[:play]       &&= hash[:play].split('++')
+          end
+        end
+
+      end
+      
+      attr_reader :call
+      def initialize(call)
+        @call = call
+        extend Adhearsion::VoIP::Commands.for(call.originating_voip_platform)
+      end
+      
+      def handle
+        variables = self.class.decode_hash call.variables[:network_script]
+        
+        answer
+        loop do
+          response = interruptable_play(*variables[:play])
+          if response && response.to_s == variables[:key].to_s
+            # Don't set a variable to pass through to dial()
+            break
+          elsif response && response.to_s != variables[:key].to_s
+            next
+          else
+            response = wait_for_digit variables[:timeout]
+            if response 
+              if response.to_s == variables[:key].to_s
+                # Don't set a variable to pass through to dial()
+                break
+              else
+                next
+              end
+            else
+              # By setting MACRO_RESULT to CONTINUE, we cancel the dial.
+              variable 'MACRO_RESULT' => "CONTINUE"
+              break
+            end
+          end
+        end
+        
+      end
+      
+    end
+  end
+end