librevox 0.2.1 → 0.3

data/README.md

@@ -7,8 +7,7 @@ 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.
+to take a simpler approach on the inside.
 
 ## Prerequisites
 
@@ -18,6 +17,9 @@ 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.
 
+Librevox doesn't work with Ruby versions below 1.9.1, and probably never will.
+This is because Librevox uses 1.9-only features such as fibers.
+
 ## Inbound listener
 
 To create an inbound listener, you should subclass `Librevox::Listener::Inbound`
@@ -85,22 +87,21 @@ 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
+    def session_initiated
       answer
 
-      play_and_get_digits "enter-number.wav", "error.wav" do |digit|
-        puts "User pressed #{digit}"
-        playback "thanks-for-the-input.wav"
-        hangup
-      end
+      digit = play_and_get_digits "enter-number.wav", "error.wav"
+      puts "User pressed #{digit}"
+      playback "thanks-for-the-input.wav"
+      hangup
     end
 
 You can also use the commands defined in `Librevox::Command`, which, to avoid
-namespace clashes, are wrapped in the `api` command:
+namespace clashes, are accessed through the `api` object:
     
-    session do
+    def session_initiated
       answer
-      api :status
+      api.status
     end
 
 They can be used in conjunction with applications, and do also take a block,

data/TODO

@@ -7,9 +7,6 @@
 
 - filter events
 
-- 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.
 
 - test how this works in async mode - I imagine that it might mess with
@@ -21,5 +18,8 @@
 
 - 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?
+- extension sugar (0.5)
+
+- graceful shutdown
+
+- handle disconnects

data/lib/librevox.rb

@@ -1,10 +1,12 @@
 require 'logger'
+require 'fiber'
 require 'eventmachine'
 require 'librevox/listener/inbound'
 require 'librevox/listener/outbound'
+require 'librevox/command_socket'
 
 module Librevox
-  VERSION = "0.2.1"
+  VERSION = "0.3"
 
   def self.options
     @options ||= {
@@ -34,14 +36,18 @@ module Librevox
   #     run SomeListener
   #     run OtherListner
   #   end
-  def self.start(klass=nil, args={}, &block)
+  def self.start klass=nil, args={}, &block
     logger.info "Starting Librevox"
-    EM.run {
+
+    EM.run do
+      trap("TERM") {stop}
+      trap("INT") {stop}
+
       block_given? ? instance_eval(&block) : run(klass, args)
-    }
+    end
   end
 
-  def self.run(klass, args={})
+  def self.run klass, args={}
     host = args.delete(:host) || "localhost"
     port = args.delete(:port)
 
@@ -51,4 +57,9 @@ module Librevox
       EM.start_server host, port || "8084", klass, args
     end
   end
+
+  def self.stop
+    logger.info "Terminating Librevox"
+    EM.stop
+  end
 end

data/lib/librevox/applications.rb

@@ -1,16 +1,15 @@
 module Librevox
-  # All applications should call `execute_app` with the following parameters:
+  # All applications should call `application` with the following parameters:
   #
   #   `name` - name of the application
-  #   `args` - arguments as a string (optional)
-  #   `params` - optional hash (optional)
+  #   `args` - arguments as a string to be sent to FreeSWITCH (optional)
+  #   `params` - parameters for tweaking the command (optional)
   #
-  # Applications *must* pass on any eventual block passed to them.
   module Applications
     # Answers an incoming call or session.
     # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_answer
-    def answer &b
-      execute_app "answer", &b
+    def answer
+      application "answer"
     end
 
     # Make an attended transfer
@@ -18,8 +17,8 @@ module Librevox
     #   att_xfer("user/davis")
     # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_att_xfer
     # @todo Add support for origination_cancel_key
-    def att_xfer endpoint, &b
-      execute_app "att_xfer", endpoint, &b
+    def att_xfer endpoint
+      application "att_xfer", endpoint
     end
 
     # Binds an application to the specified call legs.
@@ -30,12 +29,12 @@ module Librevox
     #                 :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
+    def bind_meta_app args={}
       arg_string =
         args.values_at(:key, :listen_to, :respond_on, :application).join(" ")
       arg_string += "::#{args[:parameters]}" if args[:parameters]
 
-      execute_app "bind_meta_app", arg_string, &b
+      application "bind_meta_app", arg_string
     end
 
 
@@ -53,8 +52,8 @@ module Librevox
     # @example With failover
     #   bridge ['user/coltrane', 'user/davis'], ['user/sun-ra', 'user/taylor']
     #   #=> user/coltrane,user/davis|user/sun-ra,user/taylor
-    # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_bridgecall
-    def bridge *args, &b
+    # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_bridge
+    def bridge *args
       variables = if args.last.is_a? Hash
                     # We need to sort the key/value pairs to facilitate testing.
                     # This can be removed once 1.8-compat is dropped.
@@ -71,7 +70,7 @@ module Librevox
                     args.join ","
                   end
 
-      execute_app "bridge", variables + endpoints, &b
+      application "bridge", variables + endpoints
     end
 
     # Deflect a call by sending a REFER. Takes a SIP URI as argument, rerouting
@@ -84,8 +83,8 @@ module Librevox
     #   deflect "sip:miles@davis.com"
     # @see #redirect
     # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_deflect
-    def deflect uri, &b
-      execute_app "deflect", uri, &b
+    def deflect uri
+      application "deflect", uri
     end
 
     # Exports a channel variable from the A leg to the B leg. Variables and
@@ -99,10 +98,10 @@ module Librevox
     # @example Only export to B-leg
     #   export "some_var", :local => false
     # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_export
-    def export var, args={}, &b
+    def export var, args={}
       nolocal = args[:local] == false ? "nolocal:" : "" # ugly!!111
 
-      execute_app "export", "#{nolocal}#{var}", &b
+      application "export", "#{nolocal}#{var}"
     end
 
     # Generate TGML tones
@@ -111,8 +110,8 @@ module Librevox
     # @example  Generate a DTMF string
     #   gentones "0800500005"
     # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_gentones
-    def gentones tgml, &b 
-      execute_app "gentones", tgml, &b
+    def gentones tgml 
+      application "gentones", tgml
     end
 
     # Hang up current channel
@@ -121,8 +120,8 @@ module Librevox
     # @example Hang up with a reason
     #   hangup "USER_BUSY"
     # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_hangup
-    def hangup cause="", &b
-      execute_app "hangup", cause, &b
+    def hangup cause=""
+      application "hangup", cause
     end
 
     # Plays a sound file and reads DTMF presses.
@@ -135,53 +134,53 @@ module Librevox
     #     :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
+    def play_and_get_digits file, invalid_file, args={}
       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"
+      variable    = args[:variable]     || "read_digits_var"
       regexp      = args[:regexp]       || "\\d+"
 
       args = [min, max, tries, timeout, terminators, file, invalid_file,
-        read_var, regexp].join " "
+        variable, regexp].join " "
 
-      params = {:read_var => read_var}
+      params = {:variable => variable}
 
-      execute_app "play_and_get_digits", args, params, &b
+      application "play_and_get_digits", args, params
     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
+    def playback file
+      application "playback", file
     end
 
     # Pre-answer establishes early media but does not answer.
     # @example
     #   pre_anser
     # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_pre_answer
-    def pre_answer &b
-      execute_app "pre_answer", &b
+    def pre_answer
+      application "pre_answer"
     end
 
     # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_read
-    def read file, args={}, &b
+    def read file, args={}
       min         = args[:min]          || 1
       max         = args[:max]          || 2
       terminators = args[:terminators]  || "#"
       timeout     = args[:timeout]      || 5000
-      read_var    = args[:read_var]     || "read_digits_var"
+      variable    = args[:variable]     || "read_digits_var"
 
-      arg_string = "%s %s %s %s %s %s" % [min, max, file, read_var, timeout,
+      arg_string = "%s %s %s %s %s %s" % [min, max, file, variable, timeout,
         terminators]
 
-      params = {:read_var => read_var}
+      params = {:variable => variable}
 
-      execute_app "read", arg_string, params, &b
+      application "read", arg_string, params
     end
 
     # Records a message, with an optional limit on the maximum duration of the
@@ -191,56 +190,64 @@ module Librevox
     # @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
+    def record path, params={}
       args = [path, params[:limit]].compact.join(" ")
-      execute_app "record", args, &b
+      application "record", args
     end
 
     # Redirect a channel to another endpoint. You must take care to not
     # redirect incompatible channels, as that wont have the desired effect.
     # I.e. if you redirect to a SIP URI, it should be a SIP channel.
     #
-    # #{redirect} can only be used on non-established calls, i.e. calls that
-    # has not been answered with the #{answer} application yet. If the call has
-    # been answered, use #{deflect} instead.
+    # {#redirect} can only be used on non-established calls, i.e. calls that
+    # has not been answered with the {#answer} application yet. If the call has
+    # been answered, use {#deflect} instead.
     # @example
     #   redirect "sip:freddie@hubbard.org"
-    # @see #{deflect}
+    # @see #deflect
     # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_redirect
-    def redirect uri, &b
-      execute_app "redirect", uri, &b
+    def redirect uri
+      application "redirect", uri
+    end
+
+    # Send SIP session respond code.
+    # @example Send 403 Forbidden
+    #   respond 403
+    # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_respond
+    def respond code
+      application "respond", code.to_s
     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
+    def set variable, value
+      application "set", "#{variable}=#{value}"
     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
+    def transfer context
+      application "transfer", context
     end
 
     # Unbinds a previously bound key with bind_meta_app
     # @example
     #   unbind_meta_app 3
     # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_unbind_meta_app
-    def unbind_meta_app key, &b
-      execute_app "unbind_meta_app", key.to_s, &b
+    def unbind_meta_app key
+      application "unbind_meta_app", key.to_s
     end
 
     # Unset a channel variable.
     # @example
     #   unset "foo"
     # @see http://wiki.freeswitch.org/wiki/Misc._Dialplan_Tools_unset
-    def unset variable, &b
-      execute_app "unset", variable, &b
+    def unset variable
+      application "unset", variable
     end
   end
 end

data/lib/librevox/command_socket.rb

@@ -7,7 +7,7 @@ module Librevox
   class CommandSocket
     include Librevox::Commands
 
-    def initialize(args={})
+    def initialize args={}
       @server   = args[:server] || "127.0.0.1"
       @port     = args[:port] || "8021"
       @auth     = args[:auth] || "ClueCon"
@@ -17,11 +17,12 @@ module Librevox
 
     def connect
       @socket = TCPSocket.open(@server, @port)
-      run_cmd "auth #{@auth}"
+      @socket.print "auth #{@auth}\n\n"
+      read_response
     end
 
-    def run_cmd(cmd)
-      @socket.print "#{cmd}\n\n"
+    def command *args
+      @socket.print "#{super(*args)}\n\n"
       read_response
     end
 

data/lib/librevox/commands.rb

@@ -1,5 +1,5 @@
 module Librevox
-  # All commands should call `execute_cmd` with the following parameters:
+  # All commands should call `command` with the following parameters:
   #
   #   `name` - name of the command
   #   `args` - arguments as a string (optional)
@@ -8,17 +8,25 @@ module Librevox
   module Commands
     # Executes a generic API command, optionally taking arguments as string.
     # @example
-    #   socket.execute_cmd "fsctl", "hupall normal_clearing"
+    #   socket.command "fsctl", "hupall normal_clearing"
     # @see http://wiki.freeswitch.org/wiki/Mod_commands
-    def execute_cmd(name, args="", &block)
+    def command name, args=""
       msg = "api #{name}"
-      msg << " #{args}" unless args.empty?
+      msg << " #{args}" if args && !args.empty?
+      msg
+    end
 
-      run_cmd(msg, &block)
+    def status
+      command "status"
     end
 
-    def status(&b)
-      execute_cmd "status", &b
+    # Access the hash table that comes with FreeSWITCH.
+    # @example
+    #   socket.hash :insert, :realm, :key, "value"
+    #   socket.hash :select, :realm, :key
+    #   socket.hash :delete, :realm, :key
+    def hash *args
+      command "hash", args.join("/")
     end
 
     # Originate a new call.
@@ -26,7 +34,7 @@ module Librevox
     #   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)
+    def originate url, args={}
       extension = args.delete(:extension)
       dialplan  = args.delete(:dialplan)
       context   = args.delete(:context)
@@ -35,19 +43,35 @@ module Librevox
 
       arg_string = "{#{vars}}" + 
         [url, extension, dialplan, context].compact.join(" ")
-      execute_cmd "originate", arg_string, &b
+      command "originate", arg_string
     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
+    def fsctl *args
+      command "fsctl", args.join(" ")
+    end
+
+    def hupall cause=nil
+      command "hupall", cause
     end
 
-    def hupall(cause=nil, &b)
-      execute_cmd "hupall", cause, &b
+    # Park call.
+    # @example
+    #   socket.uuid_park "592567a2-1be4-11df-a036-19bfdab2092f"
+    # @see http://wiki.freeswitch.org/wiki/Mod_commands#uuid_park
+    def uuid_park uuid
+      command "uuid_park", uuid
+    end
+
+    # Bridge two call legs together. At least one leg must be anwered.
+    # @example
+    #   socket.uuid_bridge "592567a2-1be4-11df-a036-19bfdab2092f", "58b39c3a-1be4-11df-a035-19bfdab2092f"
+    # @see http://wiki.freeswitch.org/wiki/Mod_commands#uuid_bridge
+    def uuid_bridge uuid1, uuid2
+      command "uuid_bridge", "#{uuid1} #{uuid2}"
     end
   end
 end