rami 0.1 → 0.2

data/CHANGELOG

@@ -0,0 +1,20 @@
+* 0.2 (Oct 20, 2005)
+
+* Change RamiServer and RamiClient classes to just Server and Client. Client now takes one paramater for new(), which is an instance
+  of Server.  Server.new now takes it's argumetns via a single hash, instead of setting the options via attributes after the instance
+  is created. 
+
+* Separated Drb from Rami per the suggestion of Jonathan Paisley.  You can now create a server and client without having to use Drb
+
+* Added some more examples to /bin
+
+* Fixed couple of minor bugs
+
+* Cleaned up the logging a bit.  I know I should use the ruby logging module, maybe later..
+
+
+
+* 0.1 (Oct 16, 2005)
+
+* First release of Rami
+

data/bin/example1.rb

@@ -0,0 +1,33 @@
+#!/usr/local/bin/ruby
+
+require 'rubygems'
+require 'rami'
+include Rami
+
+def print_results(t)
+  if t.size > 0
+    t.each do |array|
+      array.each {|key,value| puts "#{key}: #{value}"}
+    end
+  end
+  puts "\n\n"
+end
+
+server = Server.new({'host' => 'localhost', 'username' => 'asterisk', 'secret' => 'secret'})
+server.console =1
+server.event_cache = 100
+server.run
+
+
+client = Client.new(server)
+
+client.timeout = 10
+t =  client.ping
+print_results(t)
+
+t =  client.mailbox_count(1002)
+print_results(t)
+
+t =  client.get_events
+print_results(t)
+

data/bin/example2.rb

@@ -0,0 +1,29 @@
+#!/usr/local/bin/ruby
+
+require 'rubygems'
+require 'rami'
+include Rami
+
+def print_results(t)
+  if t.size > 0
+    t.each do |array|
+      array.each {|key,value| puts "#{key}: #{value}"}
+    end
+  end
+  puts "\n\n"
+end
+
+c = DRbObject.new(nil,"druby://localhost:9000")
+client = Client.new(c)
+
+
+client.timeout = 10
+t =  client.ping
+print_results(t)
+
+t =  client.mailbox_count(1002)
+print_results(t)
+
+t =  client.get_events
+print_results(t)
+

data/bin/server.rb

@@ -4,18 +4,11 @@ require 'rubygems'
 require 'rami'
 include Rami
 
-server = RamiServer.new
+server = Server.new({'host' => 'localhost', 'username' => 'asterisk', 'secret' => 'secret', 'console' => 0, 'event_cache' => 100})
 
-## if you want all events printed to the console set this to 1
 server.console =1
 
-## The username and secret used to login to the Asterisk manager interface
-server.username = 'asterisk'
-server.secret = 'secret'
-
-## The host and port that the manager interface is running on.  
-server.host = 'localhost'
-server.port = 5038  
+server.event_cache = 100
 
 ## DRb URI
 drburi = "druby://localhost:9000"

data/bin/test.rb

@@ -13,7 +13,9 @@ def print_results(t)
   puts "\n\n"
 end
 
-client = RamiClient.new
+c = DRbObject.new(nil,"druby://localhost:9000")
+client = Client.new(c)
+
 
 ## Redirect
 client.timeout = 10
@@ -35,11 +37,6 @@ client.timeout = 10
 t =  client.sip_peers
 print_results(t)
 
-## SIPshowpeer
-client.timeout = 10
-t =  client.sip_show_peer('test_peer')
-print_results(t)
-
 ## ParkedCalls
 client.timeout = 10
 t =  client.parked_calls
@@ -135,7 +132,7 @@ print_results(t)
 t =  client.find_events('Event','NewCallerID')
 print_results(t)
 # OR
-t =  client.find_events('any','SIP/test_extension')
+t =  client.find_events('any' => 'SIP/test_extension')
 print_results(t)
 
 ## Get all events in the state queue

data/lib/rami.rb

@@ -33,11 +33,46 @@ require 'monitor'
 require 'socket'
 require 'timeout'
 
-# A proxy server/client api for the Asterisk Manager Interface
+# Rami can be used to write standalone scripts to send commands to the Asterisk manager interface, or you can
+# use Drb and Rami::Server to run a Rami proxy server.  You can then connect to the proxy server using Rami::Client and Drb.
+# This module was written against Asterisk 1.2-beta1.  There are a few minor changes to some AMI commands
+# in Asterisk CVS HEAD.  When 1.2 is released I will update the module accordingly.
 module Rami
 
-# The Rami client library.  To use the library make sure the server has been started and then call RamiClient.new and set the 
-# host, port, and timeout attributes. All methods return an array of hashes, or an empty array if no data is available. 
+# The Rami client. 
+#
+# One possible point of confusion about the client is that it takes a server instance as the sole argument to it's new()
+# method.  This is because Rami was designed to be used with Drb.  You don't have to use Drb though.  
+# You can create and start a Server instance via it's run method, then in the same code create your Client instance
+# and submit requests to the server. A simple example..
+# 
+# require 'rubygems'
+#
+# require 'rami'
+#
+# include Rami
+#
+# server = Server.new({'host' => 'localhost', 'username' => 'asterisk', 'secret' => 'secret'})
+#
+# server.run
+#
+# client = Client.new(server)
+#
+# client.timeout = 10
+#
+# puts client.ping
+#
+# The above code will start the server and login, then execute the ping command and print the results, then exit, disconnecting
+# from asterisk.
+#
+# To connect to a running server using Drb you can create a client instance like this.:
+#
+# c = DRbObject.new(nil,"druby://localhost:9000")
+#
+# client = Client.new(c)
+#
+#
+# All Client methods return an array of hashes, or an empty array if no data is available. 
 #
 # Each hash will contain an asterisk response packet.  Note that not all response packets are always returned.  If a response
 # packet is necessary for the actual communication with asterisk, but does not in itself have any meaningful content, then
@@ -48,29 +83,23 @@ module Rami
 # I tried to document the things that need it the most. Some things should be fairly evident, such as methods for simple
 # commands like Monitor or Ping.
 # 
-# For examples, see test.rb in the bin directory.  It contains sample code for calling every available method.
+# For examples, see example1.rb, example2.rb, and test.rb in the bin directory. 
 #
 # Not all manager commands are currently supported.  This is only because I have not yet had the time to add them.  
 # I tried to add the most complicated commands first, so adding the remaining commands is fairly simple.
 # If there is a command you need let me know and I will make sure it gets included.
-# If you want to add your own action command it's fairly simple.  Add a method in RamiClient for
-# the new command, and then add a section in the RamiClient::send_action loop to harvest the response.
-class RamiClient
-
-  # Server hostname.  Default localhost
-  attr_writer :host
-  # Server port.  Default 9000
-  attr_writer :port
+# If you want to add your own action command it's fairly simple.  Add a method in Client for
+# the new command, and then add a section in the Client::send_action loop to harvest the response.
+class Client
+
   # Number of seconds before a method call will timeout. Default 10.
   attr_writer :timeout
 
-  def initialize
-    @host = 'localhost'
-    @port = 9000
+  # Takes one argument, an instance of Server OR a DrbObject pointed at a running Rami server.
+  def initialize(client)
     @timeout = 10
     @action_id = Time.now().to_f
-    DRb.start_service()
-    @client = DRbObject.new(nil,"druby://#{@host}:#{@port}")
+    @client = client
   end
 
   def absolute_timeout(channel=nil,tout=nil)
@@ -112,13 +141,13 @@ class RamiClient
   # The key is an exact match, the value is a regex.  You can also call find_events with key=any, which will match
   # any entry with the given value
   # 
-  # The returned results are deleted from the queue.  See RamiServer for more information on the queue structure.
+  # The returned results are deleted from the queue.  See Server for more information on the queue structure.
   def find_events(key=nil,value=nil)
     return @client.find_events(key,value)
   end
 
   # Get all events from the state queue.  The returned results are deleted from the queue.
-  # See RamiServer for more information on the queue structure.
+  # See Server for more information on the queue structure.
   def get_events
     return @client.get_events
   end
@@ -268,27 +297,19 @@ private
 
 end
 
-
-# RamiServer maintains one open connection to asterisk.  It uses one thread to constantly read responses and stick them into
-# the appropriate queue.  Clients connect via DRb and are each serviced in their own thread.
+# To run a standalone Rami server create a Server instance and then call it's run() method.  
+# The server will maintain one open connection to asterisk.  It uses one thread to constantly read responses and stick them into
+# the appropriate queue.
 #
 # The server uses two queues to hold responses from asterisk.  The action queue holds all responses that contain an ActionID.
 # The state queue holds all responses that do not have an ActionID.  The action queue is only used internally, while the state
-# queue can be queried via RamiClient.get_events and RamiClient.find_events. 
+# queue can be queried via Client.get_events and Client.find_events. 
 #
-# To run the server, call RamiServer.new, set the attributes, then call the run method.
-# For an example of how to run the server, see bin/server.rb.
-class RamiServer
+# For an example of how to run a standalone server, see bin/server.rb.  For using the Server and Client classes together without
+# starting a standalone server see the Client documentation.
+class Server
   # If set to 1, console logging is turned on.  Default 0
   attr_writer :console
-  # Asterisk manager username.  Default asterisk.
-  attr_writer :username
-  # Asterisk manager secret.  Default secret. 
-  attr_writer :secret
-  # Asterisk manager hostname.  Default localhost
-  attr_writer :host
-  # Asterisk manager port.  Default 5038
-  attr_writer :port
   # The number of responses to hold in the state queue. The state queue is a FIFO list.  Default is 100.
   attr_writer :event_cache
 
@@ -296,14 +317,24 @@ Thread.current.abort_on_exception=true
 
 include DRbUndumped
 
-def initialize
-    @console = 0
-    @username = 'asterisk'
-    @secret = 'secret'
-    @host = 'localhost'
-    @port = 5038
+# Takes a hash with the following keys:
+# * host - hostname the AMI is running on
+# * port - port number the AMI is running on
+# * username - AMI username
+# * secret - AMI secret
+# * console - Set to 1 for console logging.  Default is 0 (off)
+# * event_cache - Number of responses to hold in the event queue. Default 100
+#
+# console and event_cache are also attributes, so they can be changed after calling Server.new
+def initialize(options = {})
+    @console = options['console'] || 0
+    @username = options['username'] || 'asterisk'
+    @secret = options['secret'] || 'secret'
+    @host = options['host'] || 'localhost'
+    @port = options['port'] || 5038
+    @event_cache = options['event_cache'] || 100
+
     @eventcount = 1
-    @event_cache = 100
 
     @sock = nil
     @socklock = nil
@@ -324,6 +355,12 @@ end
 
 private
 
+def logger(type,msg)
+  if @console == 1
+    print "#{Time.now} #{type} #{@eventcount}: #{msg}"
+  end
+end
+
 def connect
   @sock = TCPSocket.new(@host,@port)
   login = {'Action' => 'login', 'Username' => @username, 'Secret' => @secret, 'Events' => 'On'}
@@ -337,9 +374,7 @@ def connect
           key,value = parseline(line) if line.include?(':')
           accum[key] = value
         end
-        if @console == 1
-          print "#{Time.now} RECV #{@eventcount}: #{line}"
-        end
+        logger('RECV',"#{line}")
         if line == "\r\n" and accum['Message'] == 'Authentication accepted' and accum['Response'] == 'Success'
           login =1
           @eventcount += 1
@@ -349,7 +384,7 @@ def connect
     end
   return true
   end
-rescue Exception => e
+rescue Timeout::Error => e
   puts "LOGIN TIMEOUT"
   return false
 end
@@ -365,23 +400,17 @@ def mainloop
       @sock.each("\r\n") do |line|
         linecount += 1
         type = 'state'
-        if @console == 1
-          print "#{Time.now} RECV #{@eventcount}: #{line}"
-        end
+        logger('RECV', "#{line}")
         if line == "\r\n"
           if event.size == 0
-            if @console == 1
-              print "#{Time.now} MSG: #{@eventcount} RECEIVED EXTRA CR/LF #{line}"
-            end
+            logger('MSG',"RECEIVED EXTRA CR/LF #{line}")
             next
           end
           if event['ActionID']
             type = 'action'
           end
-
-          if @console == 1
-            print "#{Time.now} MSG: #{@eventcount} finished (type=#{type}) #{line}"
-          end
+          
+          logger('MSG',"finished (type=#{type}) #{line}")
 
           if type == 'action'
             @action_events.synchronize do
@@ -427,18 +456,15 @@ def parseline(line)
 
 end
 
-def writelog(msg)
-  print "#{Time.now} #{msg}\r\n"
-end
 
 def writesock(action)
   @socklock.synchronize do
     action.each do |key,value|
       @sock.write("#{key}: #{value}\r\n")
-      print "#{Time.now} SEND #{@eventcount}: #{key}: #{value}\r\n"
+      logger('SEND',"#{key}: #{value}\r\n")
     end
     @sock.write("\r\n")
-    print "#{Time.now} SEND #{@eventcount}: \r\n"
+    logger('SEND',"\r\n")
   end
 end
 
@@ -456,9 +482,9 @@ def run
   mainloop
 end
 
-# Should only be called via Drb by RamiClient
+# Should only be called via Client
 def find_events(key=nil,value=nil)
-  print "#{Time.now} find_events: #{key}: #{value}\r\n"
+  logger('find_events',"#{key}: #{value}")
   found = []
   @state_events.synchronize do
     if @state_events.empty?
@@ -479,7 +505,7 @@ def find_events(key=nil,value=nil)
   end
 end
 
-# Should only be called via Drb by RamiClient
+# Should only be called via Client
 def get_events
   found = []
   @state_events.synchronize do
@@ -496,7 +522,7 @@ def get_events
   end
 end
 
-# Should only be called via Drb by RamiClient
+# Should only be called via Client
 def send_action(action=nil,t=10)
   sent_id = action['ActionID'].to_s
   result = []

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: rami
 version: !ruby/object:Gem::Version 
-  version: "0.1"
-date: 2005-10-17 00:00:00 -07:00
+  version: "0.2"
+date: 2005-10-20 00:00:00 -07:00
 summary: A proxy server/client api for the Asterisk Manager Interface
 require_paths: 
   - lib
@@ -31,10 +31,13 @@ authors:
 files: 
   - README
   - LICENSE
+  - CHANGELOG
   - manager.txt
   - lib/rami.rb
   - bin/server.rb
   - bin/test.rb
+  - bin/example1.rb
+  - bin/example2.rb
 test_files: []
 rdoc_options: []
 extra_rdoc_files: []