librevox 0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 rubyists.com (TJ Vanderpoel, Jayson Vaughn, Michael Fellinger, Kevin Berry)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,159 @@
+# Librevox
+
+> An EventMachine-based Ruby library for interacting with the open source 
+> telephony platform [FreeSWITCH](http://www.freeswitch.org).
+
+Librevox eventually came to life during a major rewrite of
+[Freeswitcher](http://code.rubyists.com/projects/fs/). Not everything would
+fit into the existing architecture, and I felt that a blank slate was needed.
+Librevox and Freeswitcher looks much alike on the outside, but Librevox tries
+to take a simpler approach on the inside. Eventually this is still beta
+software, and needs some real-life testing before seeing a regular release.
+
+## Prerequisites
+
+Librevox lets you interact with FreeSWITCH through mod_event_socket. You
+should know how the event socket works, and the differences between inbound and
+outbound event sockets before proceeding. The
+[wiki page on mod_event_socket](http://wiki.freeswitch.org/wiki/Event_Socket) is
+a good place to start.
+
+## Inbound listener
+
+To create an inbound listener, you should subclass `Librevox::Listener::Inbound`
+and add custom behaviour to it. An inbound listener subscribes to all events
+from FreeSWITCH, and lets you react on events in two different ways:
+
+1.      By overiding `on_event` which gets called every time an event arrives.
+
+2.      By adding an event hook with `event`, which will get called every time
+        an event with the specified name arrives.
+
+The header and content of the event is accessible through `event`.
+
+Below is an example of an inbound listener utilising all the aforementioned
+techniques:
+
+    require 'librevox'
+
+    class MyInbound < Librevox::Listener::Inbound
+      def on_event
+        puts "Got event: #{event.content[:event_name]}"
+      end
+     
+      # You can add a hook for a certain event:
+      event :channel_hangup do
+        # It is instance_eval'ed, so you can use your instance methods etc:
+        do_something
+      end
+     
+      def do_something
+        ...
+      end
+    end
+
+## Outbound listener
+
+You create an outbound listener by subclassing `Librevox::Listener::Outbound`. 
+
+### Events
+
+An outbound listener has the same event functionality as the inbound listener,
+but it only receives events related to that given session.
+
+### Dialplan
+
+When a call is made and Freeswitch connects to the outbound event listener,
+the `session` callback is executed. This is where you set up your dialplan:
+
+    session do
+      answer
+      set "some_var", "some value"
+      playback "path/to/file"
+      hangup
+    end
+
+When using applications that expect a reply, such as `play_and_get_digits`,
+you have to use callbacks to read the value, as the function itself returns
+immediately due to the async nature of EventMachine:
+
+    session do
+      answer
+
+      play_and_get_digits "enter-number.wav", "error.wav" do |digit|
+        puts "User pressed #{digit}"
+        playback "thanks-for-the-input.wav"
+        hangup
+      end
+    end
+
+You can also use the commands defined in `Librevox::Command`, which, to avoid
+namespace clashes, are wrapped in the `api` command:
+    
+    session do
+      answer
+      api :status
+    end
+
+They can be used in conjunction with applications, and do also take a block,
+passing the response to an eventual block argument.
+
+## Starting listeners
+
+To start a single listener, connection/listening on localhost on the default
+port is quite simple:
+
+    Librevox.start SomeListener
+
+it takes an optional hash with arguments:
+
+    Librevox.start SomeListener, :host => "1.2.3.4", :port => "8087", :auth => "pwd"
+
+Multiple listeners can be started at once by passing a block to `Librevox.start`:
+
+    Librevox.start do
+      run SomeListener
+      run OtherListener, :port => "8080"
+    end
+
+## Using `Librevox::CommandSocket`
+
+Librevox also ships with a CommandSocket class, which allows you to connect
+to the FreeSWITCH management console, from which you can originate calls,
+restart FreeSWITCH etc.
+
+    >> require `librevox`
+    => true
+    
+    >> socket = Librevox::CommandSocket.new
+    => #<Librevox::CommandSocket:0xb7a89104 @server=“127.0.0.1”,
+        @socket=#<TCPSocket:0xb7a8908c>, @port=“8021”, @auth=“ClueCon”>
+
+    >> socket.originate('sofia/user/coltrane', :extension => "1234")
+    >> #<Librevox::Response:0x10179d388 @content="+OK de0ecbbe-e847...">
+    
+    >> socket.status
+    >> > #<Librevox::Response:0x1016acac8 ...>
+
+## Further documentation
+
+All applications and commands are documented in the code. You can run
+`yardoc` from the root of the source tree to generate YARD docs. Look under
+the `Librevox::Commands` and `Librevox::Applications` modules.
+
+## Extras
+
+* Source: [http://github.com/ichverstehe/librevox](http://github.com/ichverstehe/librevox)
+* API docs: [http://rdoc.info/projects/ichverstehe/librevox](http://rdoc.info/projects/ichverstehe/librevox)
+* Mailing list: librevox@librelist.com
+* IRC: #librevox @ irc.freenode.net
+
+## License
+
+(c) 2009 Harry Vangberg <harry@vangberg.name>
+
+Librevox was inspired by and uses code from Freeswitcher, which is distributed
+under the MIT license and (c) 2009 The Rubyists (Jayson Vaughn, Tj Vanderpoel,
+Michael Fellinger, Kevin Berry), Harry Vangberg
+
+Distributed under the terms of the MIT license.

data/Rakefile

@@ -0,0 +1,6 @@
+desc "Run tests"
+task :default => :test
+
+task :test do
+  sh "bacon -Ilib -a -q"
+end

data/TODO

@@ -0,0 +1,24 @@
+- the execute_app/run_app business might be done better, simpler. e.g.
+  having to pass the block for every command becomes a bit tedious.
+
+- move test suite from bacon -> test/unit.
+
+- map more commands/applications.
+
+- test how this works in async mode - I imagine that it might mess with
+  @command_queue
+
+- how can applications be used w/ command socket? would be nice if you could
+  do e.g.  originate("user/coltrane", :endpoint => bridge("user/davis"))  and
+  it would translate to  "originate user/coltrane &bridge(user/davis)"
+
+- add logger.
+
+- check command/application input and raise ArgumentError.
+
+- maybe let commands handle the response, so something useful could be returned?
+
+- possibly catch all exceptions, so everything doesn't die? or should this be
+  be the users responsibilty?
+
+- filter events

data/lib/librevox.rb

@@ -0,0 +1,35 @@
+require 'eventmachine'
+require 'librevox/listener/inbound'
+require 'librevox/listener/outbound'
+
+module Librevox
+  # When called without a block, it will start the listener that is passed as
+  # first argument:
+  #   
+  #   Librevox.start SomeListener
+  #
+  # To start multiple listeners, call with a block and use `run`:
+  #
+  #   Librevox.start do
+  #     run SomeListener
+  #     run OtherListner
+  #   end
+  def self.start(klass=nil, args={}, &block)
+    EM.run {
+      block_given? ? instance_eval(&block) : run(klass, args)
+    }
+  end
+
+  def self.run(klass, args={})
+    host = args.delete(:host) || "localhost"
+    port = args.delete(:port)
+
+    if klass.ancestors.include? Librevox::Listener::Inbound
+      port ||= "8021"
+      EM.connect host, port, klass, args
+    elsif klass.ancestors.include? Librevox::Listener::Outbound
+      port ||= "8084"
+      EM.start_server host, port, klass, args
+    end
+  end
+end

data/lib/librevox/applications.rb

@@ -0,0 +1,127 @@
+module Librevox
+  # All applications should call `execute_app` with the following parameters:
+  #
+  #   `name` - name of the application
+  #   `args` - arguments as a string (optional)
+  #   `params` - optional hash (optional)
+  #
+  # Applications *must* pass on any eventual block passed to them.
+  module Applications
+    # Answers an incoming call or session.
+    def answer(&b)
+      execute_app "answer", &b
+    end
+
+    # Binds an application to the specified call legs.
+    # @example 
+    #   bind_meta_app :key          => 2,
+    #                 :listen_to    => "a",
+    #                 :respond_on   => "s",
+    #                 :application  => "execute_extension",
+    #                 :parameters   => "dx XML features"
+    # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_bind_meta_app
+    def bind_meta_app(args={}, &b)
+      key         = args[:key]
+      listen_to   = args[:listen_to]
+      respond_on  = args[:respond_on]
+      application = args[:application]
+      parameters  = args[:parameters] ? "::#{args[:parameters]}" : ""
+
+      arg_string = "%s %s %s %s%s" % [key, listen_to, respond_on, application,
+        parameters]
+
+      execute_app "bind_meta_app", arg_string, &b
+    end
+
+    # Bridges an incoming call to an endpoint
+    # @example
+    #   bridge "user/coltrane", "user/backup-office"
+    # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_bridgecall
+    def bridge(*endpoints, &b)
+      execute_app "bridge", endpoints.join(","), &b
+    end
+
+    def hangup(cause="", &b)
+      execute_app "hangup", cause, &b
+    end
+
+    # Plays a sound file and reads DTMF presses.
+    # @example 
+    #   play_and_get_digits "please-enter.wav", "wrong-choice.wav",
+    #     :min          => 1,
+    #     :max          => 2,
+    #     :tries        => 3,
+    #     :terminators  => "#",
+    #     :timeout      => 5000,
+    #     :regexp       => '\d+'
+    # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_play_and_get_digits
+    def play_and_get_digits(file, invalid_file, args={}, &b)
+      min         = args[:min]          || 1
+      max         = args[:max]          || 2
+      tries       = args[:tries]        || 3
+      terminators = args[:terminators]  || "#"
+      timeout     = args[:timeout]      || 5000
+      read_var    = args[:read_var]     || "read_digits_var"
+      regexp      = args[:regexp]       || "\\d+"
+
+      args = [min, max, tries, timeout, terminators, file, invalid_file,
+        read_var, regexp].join " "
+
+      params = {:read_var => read_var}
+
+      execute_app "play_and_get_digits", args, params, &b
+    end
+
+    # Plays a sound file on the current channel.
+    # @example
+    #   playback "/path/to/file.wav"
+    # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_playback
+    def playback(file, &b)
+      execute_app "playback", file, &b
+    end
+
+    # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_read
+    def read(file, args={}, &b)
+      min         = args[:min]          || 1
+      max         = args[:max]          || 2
+      terminators = args[:terminators]  || "#"
+      timeout     = args[:timeout]      || 5000
+      read_var    = args[:read_var]     || "read_digits_var"
+
+      arg_string = "%s %s %s %s %s %s" % [min, max, file, read_var, timeout,
+        terminators]
+
+      params = {:read_var => read_var}
+
+      execute_app "read", arg_string, params, &b
+    end
+
+    # Records a message, with an optional limit on the maximum duration of the
+    # recording.
+    # @example Without limit
+    #   record "/path/to/new/file.wac"
+    # @example With 20 second limit
+    #   record "/path/to/new/file.wac", :limit => 20
+    # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_record
+    def record(path, params={}, &b)
+      args = [path, params[:limit]].compact.join(" ")
+      execute_app "record", args, &b
+    end
+
+    # Sets a channel variable.
+    # @example
+    #   set "some_var", "some value"
+    # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_set
+    def set(variable, value, &b)
+      execute_app "set", "#{variable}=#{value}", &b
+    end
+
+    # Transfers the current channel to a new context.
+    # @example
+    #   transfer "new_context"
+    # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_transfer
+    def transfer(context, &b)
+      execute_app "transfer", context, &b
+    end
+  end
+end

data/lib/librevox/command_socket.rb

@@ -0,0 +1,50 @@
+require 'socket'
+require 'librevox/response'
+require 'librevox/commands'
+require 'librevox/applications'
+
+module Librevox
+  class CommandSocket
+    include Librevox::Commands
+
+    def initialize(args={})
+      @server   = args[:server] || "127.0.0.1"
+      @port     = args[:port] || "8021"
+      @auth     = args[:auth] || "ClueCon"
+
+      connect unless args[:connect] == false
+    end
+
+    def connect
+      @socket = TCPSocket.open(@server, @port)
+      run_cmd "auth #{@auth}"
+    end
+
+    def run_cmd(cmd)
+      @socket.print "#{cmd}\n\n"
+      read_response
+    end
+
+    def read_response
+      response = Librevox::Response.new
+      until response.command_reply? or response.api_response?
+        response.headers = read_headers 
+      end
+
+      length = response.headers[:content_length].to_i
+      response.content = @socket.read(length) if length > 0
+
+      response
+    end
+
+    def read_headers
+      headers = ""
+
+      while line = @socket.gets and !line.chomp.empty?
+        headers += line
+      end
+
+      headers
+    end
+  end
+end

data/lib/librevox/commands.rb

@@ -0,0 +1,53 @@
+module Librevox
+  # All commands should call `execute_cmd` with the following parameters:
+  #
+  #   `name` - name of the command
+  #   `args` - arguments as a string (optional)
+  #
+  # Commands *must* pass on any eventual block passed to them.
+  module Commands
+    # Executes a generic API command, optionally taking arguments as string.
+    # @example
+    #   socket.execute_cmd "fsctl", "hupall normal_clearing"
+    # @see http://wiki.freeswitch.org/wiki/Mod_commands
+    def execute_cmd(name, args="", &block)
+      msg = "api #{name}"
+      msg << " #{args}" unless args.empty?
+
+      run_cmd(msg, &block)
+    end
+
+    def status(&b)
+      execute_cmd "status", &b
+    end
+
+    # Originate a new call.
+    # @example Minimum options
+    #   socket.originate 'sofia/user/coltrane', :extension => "1234"
+    # @example With :dialplan and :context
+    # @see http://wiki.freeswitch.org/wiki/Mod_commands#originate
+    def originate(url, args={}, &b)
+      extension = args.delete(:extension)
+      dialplan  = args.delete(:dialplan)
+      context   = args.delete(:context)
+
+      vars = args.map {|k,v| "#{k}=#{v}"}.join(",")
+
+      arg_string = "{#{vars}}" + 
+        [url, extension, dialplan, context].compact.join(" ")
+      execute_cmd "originate", arg_string, &b
+    end
+
+    # FreeSWITCH control messages.
+    # @example
+    #   socket.fsctl :hupall, :normal_clearing
+    # @see http://wiki.freeswitch.org/wiki/Mod_commands#fsctl
+    def fsctl(*args, &b)
+      execute_cmd "fsctl", args.join(" "), &b
+    end
+
+    def hupall(cause=nil, &b)
+      execute_cmd "hupall", cause, &b
+    end
+  end
+end