sevenscale-adhearsion 0.7.1003 → 0.8.0

data/lib/adhearsion/initializer.rb

@@ -1,6 +1,45 @@
 module Adhearsion
   
+  class << self
+    
+    ##
+    # Shuts down the framework.
+    #
+    def self.shutdown!
+      ahn_log "Shutting down gracefully at #{Time.now}."
+      Events.stop!
+      exit
+    end    
+    
+  end
   class PathString < String
+    
+    class << self
+      
+      ##
+      # Will return a PathString for the application root folder to which the specified arbitrarily nested subfolder belongs.
+      # It works by traversing parent directories looking for the .ahnrc file. If no .ahnrc is found, nil is returned.
+      #
+      # @param [String] folder The path to the directory which should be a 
+      # @return [nil] if the subdirectory does not belong to a parent Adhearsion app directory
+      # @return [PathString] if a directory is found 
+      #
+      def from_application_subdirectory(folder)
+        folder = File.expand_path folder
+        ahn_rc = nil
+        
+        until ahn_rc || folder == "/"
+          possible_ahn_rc = File.join(folder, ".ahnrc")
+          if File.exists?(possible_ahn_rc)
+            ahn_rc = possible_ahn_rc
+          else
+            folder = File.expand_path(folder + "/..")
+          end
+        end
+        ahn_rc ? new(folder) : nil
+      end
+    end
+    
     attr_accessor :component_path, :dialplan_path, :log_path
     
     def initialize(path)
@@ -27,10 +66,6 @@ module Adhearsion
       self.base_path = original_path
     end
     
-    def dial_plan_named(name)
-      File.join(dialplan_path, name)
-    end
-    
     private
       def build_path_for(path)
         File.join(to_s, path)
@@ -66,8 +101,6 @@ module Adhearsion
   
     attr_reader :path, :daemon, :pid_file, :log_file, :ahn_app_log_directory
     
-    DEFAULT_FRAMEWORK_EVENT_CALLBACK_NAMES = [:after_initialized, :shutdown]
-    
     # Creation of pid_files
     #
     #  - You may want to have Adhearsion create a process identification
@@ -89,48 +122,41 @@ module Adhearsion
     
     def start
       self.class.ahn_root = path
+      
       resolve_pid_file_path
       resolve_log_file_path
       switch_to_root_directory
       catch_termination_signal
       bootstrap_rc
-      load_all_init_files
-      init_modules
       daemonize! if should_daemonize?
       initialize_log_file
+      load_all_init_files
+      init_components_subsystem
+      init_modules
+      init_events_subsystem
       create_pid_file if pid_file
       load_components
-      init_events
+      init_events_file
+      
       ahn_log "Adhearsion initialized!"
       
       trigger_after_initialized_hooks
-      join_framework_threads
+      join_important_threads
       
       self
     end
     
-    def init_events
-      if Paths.manager_for? "events"
-        framework = Events.register_namespace_path(:framework)
-        DEFAULT_FRAMEWORK_EVENT_CALLBACK_NAMES.each do |framework_event_callback_name|
-          framework.register_callback_name framework_event_callback_name
-        end
-        Events.load_definitions_from_files *all_events
-      else
-        ahn_log.events.warn 'No "events" section in .ahnrc. Skipping its initialization.'
-      end
+    def default_pid_path
+      File.join AHN_ROOT, 'adhearsion.pid'
     end
     
-    def initialize_log_file
-      Dir.mkdir(ahn_app_log_directory) unless File.directory? ahn_app_log_directory
-      file_logger = Log4r::FileOutputter.new("Main Adhearsion log file", :filename => log_file, :trunc => false)
-      
-      if should_daemonize?
-        Logging::AdhearsionLogger.outputters  = file_logger
-      else
-        Logging::AdhearsionLogger.outputters << file_logger
+    def resolve_pid_file_path
+      @pid_file = if pid_file.equal?(true) then default_pid_path
+      elsif pid_file then pid_file
+      elsif pid_file.equal?(false) then nil
+      # FIXME @pid_file = @daemon? Assignment or equality? I'm assuming equality.
+      else @pid_file = @daemon ? default_pid_path : nil
       end
-      Logging::DefaultAdhearsionLogger.redefine_outputters
     end
     
     def resolve_log_file_path      
@@ -138,18 +164,101 @@ module Adhearsion
       @log_file = File.expand_path(ahn_app_log_directory + "/adhearsion.log")
     end
     
-    def create_pid_file(file = pid_file)
-      if file
-        File.open pid_file, 'w' do |file|
-          file.puts Process.pid
+    def switch_to_root_directory
+      Dir.chdir AHN_ROOT
+    end
+    
+    def catch_termination_signal
+      %w'INT TERM'.each do |process_signal|
+        trap process_signal do
+          ahn_log "Shutting down gracefully at #{Time.now}."
+          Events.trigger :shutdown
+          exit
         end
-        
-        Hooks::TearDown.create_hook do
-          File.delete(pid_file) if File.exists?(pid_file)
+      end
+    end
+    
+    ##
+    # This step in the initialization process loads the .ahnrc in the given app folder. With the information in .ahnrc, we
+    # can continue the initialization knowing where certain files are specifically.
+    #
+    def bootstrap_rc
+      rules = self.class.get_rules_from AHN_ROOT
+      
+      AHN_CONFIG.ahnrc = rules
+      
+      # DEPRECATION: Check if the old paths format is being used. If so, abort and notify.
+      if rules.has_key?("paths") && rules["paths"].kind_of?(Hash)
+        paths = rules["paths"].each_pair do |key,value|
+          if value.kind_of?(Hash)
+            if value.has_key?("directory") || value.has_key?("pattern")
+              puts
+              puts *caller
+              puts
+                            
+              abort <<-WARNING
+Deprecation Warning
+-------------------
+The (hidden) .ahnrc file in this app is of an older format and needs to be fixed.
+
+There is a rake task to automatically fix it or you can do it manually. Note: it's
+best if you do it manually so you can retain the YAML comments in your .ahnrc file.
+  
+The rake task is called "deprecations:fix_ahnrc_path_format". 
+
+To do it manually, find all entries in the "paths" section of your ".ahnrc" file
+which look like the following:
+
+paths:
+  key_name_could_be_anything:
+    directory: some_folder
+    pattern: *.rb
+
+Note: the "models" section had this syntax before:
+
+models:
+  directory: models
+  pattern: "*.rb"
+
+The NEW syntax is as follows (using models as an example):
+
+models: models/*.rb
+
+This new format is much cleaner.
+
+Adhearsion will abort until you fix this. Sorry for the incovenience.
+              WARNING
+            end
+          end
+        end
+      end
+      
+      gems = rules['gems']
+      if gems.kind_of?(Hash) && gems.any? && respond_to?(:gem)
+        gems.each_pair do |gem_name,properties_hash|
+          if properties_hash && properties_hash["version"]
+            gem gem_name, properties_hash["version"]
+          else
+            gem gem_name
+          end
+          if properties_hash
+            case properties_hash["require"]
+              when Array
+                properties_hash["require"].each { |lib| require lib }
+              when String
+                require properties_hash["require"]
+            end 
+          end
         end
       end
     end
     
+    def load_all_init_files
+      init_files_from_rc = AHN_CONFIG.files_from_setting("paths", "init").map { |file| File.expand_path(file) }
+      already_loaded_init_files = Array(@loaded_init_files).map { |file| File.expand_path(file) }
+      (init_files_from_rc - already_loaded_init_files).each { |init| load init }
+    end
+    
     def init_modules
       require 'adhearsion/initializer/database.rb'
       require 'adhearsion/initializer/asterisk.rb'
@@ -164,28 +273,23 @@ module Adhearsion
       # FreeswitchInitializer.start if AHN_CONFIG.freeswitch_enabled?
     end
     
-    def resolve_pid_file_path
-      @pid_file = if pid_file.equal?(true) then default_pid_path
-      elsif pid_file then pid_file
-      elsif pid_file.equal?(false) then nil
-      # FIXME @pid_file = @daemon? Assignment or equality? I'm assuming equality.
-      else @pid_file = @daemon ? default_pid_path : nil
+    def init_events_subsystem
+      application_events_files = AHN_CONFIG.files_from_setting("paths", "events")
+      if application_events_files.any?
+        Events.register_callback(:shutdown) do
+          ahn_log.events "Performing a graceful stop of events subsystem"
+          Events.framework_theatre.graceful_stop!
+        end
+        Events.framework_theatre.start!
+      else
+        ahn_log.events.warn 'No entries in the "events" section of .ahnrc. Skipping its initialization.'
       end
     end
     
-    def switch_to_root_directory
-      Dir.chdir AHN_ROOT
-    end
-    
-    def catch_termination_signal
-      Hooks::TearDown.catch_termination_signals
-    end
-    
-    def load_all_init_files
-      if Paths.manager_for? "init"
-        init_files_from_rc = all_inits.map { |file| File.expand_path(file) }
-        already_loaded_init_files = Array(@loaded_init_files).map { |file| File.expand_path(file) }
-        (init_files_from_rc - already_loaded_init_files).each { |init| load init }
+    def init_events_file
+      application_events_files = AHN_CONFIG.files_from_setting("paths", "events")
+      application_events_files.each do |file|
+        Events.framework_theatre.load_events_file file
       end
     end
     
@@ -199,47 +303,69 @@ module Adhearsion
       daemonize log_file
     end
     
-    def load_components
-      ComponentManager.load
-      ComponentManager.start
+    def initialize_log_file
+      Dir.mkdir(ahn_app_log_directory) unless File.directory? ahn_app_log_directory
+      file_logger = Log4r::FileOutputter.new("Main Adhearsion log file", :filename => log_file, :trunc => false)
+      
+      if should_daemonize?
+        Logging::AdhearsionLogger.outputters  = file_logger
+      else
+        Logging::AdhearsionLogger.outputters << file_logger
+      end
+      Logging::DefaultAdhearsionLogger.redefine_outputters
     end
     
-    def trigger_after_initialized_hooks
-      Hooks::AfterInitialized.trigger_hooks
+    def create_pid_file(file = pid_file)
+      if file
+        File.open pid_file, 'w' do |file|
+          file.puts Process.pid
+        end
+        
+        Events.register_callback :shutdown do
+          File.delete(pid_file) if File.exists?(pid_file)
+        end
+      end
     end
     
-    def join_framework_threads
-      Hooks::ThreadsJoinedAfterInitialized.trigger_hooks
+    def init_components_subsystem
+      @components_directory = File.expand_path "components"
+      if File.directory? @components_directory
+        Components.component_manager = Components::ComponentManager.new @components_directory
+        Kernel.send(:const_set, :COMPONENTS, Components.component_manager.lazy_config_loader)
+        Components.component_manager.globalize_global_scope!
+        Components.component_manager.extend_object_with(Theatre::CallbackDefinitionLoader, :events)
+      else
+        ahn_log.warn "No components directory found. Not initializing any components."
+      end
     end
     
-    def bootstrap_rc
-      rules = self.class.get_rules_from AHN_ROOT
-      
-      paths = rules['paths']
-      paths.each_pair do |path_name, pattern_or_ruleset|
-        if pattern_or_ruleset.kind_of? Hash
-          directory, pattern = pattern_or_ruleset['directory'] || '.', pattern_or_ruleset['pattern'] || '*'
-          Paths.manager_for path_name, :pattern => File.join(directory, pattern)
-        else
-          directory, pattern = '.', pattern_or_ruleset
-          Paths.manager_for path_name, :pattern => File.join(directory,pattern)
-        end
-      end
-      
-      gems = rules['gems']
-      if gems.kind_of?(Hash) && gems.any? && respond_to?(:gem)
-        gems.each_pair do |gem_name,properties_hash|
-          if properties_hash && properties_hash["version"]
-            gem gem_name, properties_hash["version"]
-          else
-            gem gem_name
-          end
-        end
+    def load_components
+      if Components.component_manager
+        Components.component_manager.load_components
       end
     end
     
-    def default_pid_path
-      File.join AHN_ROOT, 'adhearsion.pid'
+    def trigger_after_initialized_hooks
+      Events.trigger_immediately :after_initialized
+    end
+    
+    ##
+    # This method will block Thread.main() until calling join() has returned for all Threads in IMPORTANT_THREADS.
+    # Note: IMPORTANT_THREADS won't always contain Thread instances. It simply requires the objects respond to join().
+    #
+    def join_important_threads
+      # Note: we're using this ugly accumulator to ensure that all threads have ended since IMPORTANT_THREADS will almost
+      # certainly change sizes after this method is called.
+      index = 0
+      until index == IMPORTANT_THREADS.size
+        begin
+          IMPORTANT_THREADS[index].join
+        rescue => e
+          ahn_log.error "Error after join()ing Thread #{thread.inspect}. #{e.message}"
+        ensure
+          index = index + 1
+        end
+      end
     end
     
     class InitializationFailedError < Exception; end

data/lib/adhearsion/tasks/deprecations.rb

@@ -0,0 +1,59 @@
+namespace :deprecations do
+  desc <<-DESC
+Older versions of Adhearsion had an .ahnrc "paths" section similar to the following...
+
+  paths:
+    models:
+      directory: models
+      pattern: *.rb
+
+This has been deprecated. The new format is this:
+
+  paths:
+    models: {models,gui/app/models}/*.rb
+
+This Rake task will fix your .ahnrc if you have 
+  DESC
+  task :fix_ahnrc_path_format do
+    puts "\nThis will remove all comments from your .ahnrc file. A backup will be created as .ahnrc.backup."
+    puts "If you wish to do this manually to preserve your comments, simply overwrite .ahnrc with .ahnrc.backup"
+    puts "and apply the change manually."
+    puts 
+    
+    require 'fileutils'
+    require 'yaml'
+    
+    ahnrc_file = File.expand_path(".ahnrc")
+    
+    FileUtils.cp ahnrc_file, ahnrc_file + ".backup"
+    ahnrc_contents = YAML.load_file ahnrc_file
+    
+    abort '.ahnrc does not have a "paths" section!' unless ahnrc_contents.has_key? "paths"
+    
+    paths = ahnrc_contents["paths"]
+    paths.clone.each_pair do |key,value|
+      if value.kind_of?(Hash)
+        if value.has_key?("directory") || value.has_key?("pattern")
+          directory, pattern = value.values_at "directory", "pattern"
+          new_path = "#{directory}/#{pattern}"
+          
+          puts "!!! CHANGING KEY #{key.inspect}!"
+          puts "!!! NEW: #{new_path.inspect}"
+          puts "!!! OLD:\n#{{key => value}.to_yaml.sub("---", "")}\n\n"
+          
+          paths[key] = new_path
+        end
+      end
+    end
+    
+    ahnrc_contents["paths"] = paths
+    new_yaml = ahnrc_contents.to_yaml.gsub("--- \n", "")
+    
+    puts "New .ahnrc file:\n" + ("#" * 25) + "\n"
+    puts new_yaml
+    puts '#' * 25
+    
+    File.open(ahnrc_file, "w") { |file| file.puts new_yaml }
+    puts "Wrote to .ahnrc. Done!"
+  end
+end

data/lib/adhearsion/tasks.rb

@@ -4,6 +4,7 @@ require 'adhearsion/tasks/database'
 require 'adhearsion/tasks/testing'
 require 'adhearsion/tasks/generating'
 require 'adhearsion/tasks/lint'
+require 'adhearsion/tasks/deprecations'
 
 namespace :adhearsion do
   desc "Dump useful information about this application's adhearsion environment"
@@ -12,4 +13,4 @@ namespace :adhearsion do
   end
 end
 
-task :default => "adhearsion:about"
+task :default => "adhearsion:about"

data/lib/adhearsion/version.rb

@@ -1,8 +1,8 @@
 module Adhearsion #:nodoc:
   module VERSION #:nodoc:
-    MAJOR = 0   unless defined? MAJOR
-    MINOR = 7   unless defined? MINOR
-    TINY  = 999 unless defined? TINY
+    MAJOR = 0 unless defined? MAJOR
+    MINOR = 8 unless defined? MINOR
+    TINY  = 0 unless defined? TINY
 
     STRING = [MAJOR, MINOR, TINY].join('.') unless defined? STRING
   end

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

@@ -12,8 +12,8 @@ module Adhearsion
             end
             
             def serve(io)
-              Hooks::BeforeCall.trigger_hooks
-          	  call = Adhearsion.receive_call_from(io)
+              call = Adhearsion.receive_call_from(io)
+              Events.trigger_immediately([:asterisk, :before_call], call)
           	  ahn_log.agi "Handling call with variables #{call.variables.inspect}"
           	  
           	  return DialPlan::ConfirmationManager.handle(call) if DialPlan::ConfirmationManager.confirmation_call?(call)
@@ -26,16 +26,16 @@ module Adhearsion
               call.hangup!
             rescue FailedExtensionCallException => failed_call
               begin
-                ahn_log.agi "Received \"failed\" meta-call with :failed_reason => #{failed_call.call.failed_reason.inspect}. Executing OnFailedCall hooks."
-                Hooks::OnFailedCall.trigger_hooks(failed_call.call)
+                ahn_log.agi "Received \"failed\" meta-call with :failed_reason => #{failed_call.call.failed_reason.inspect}. Executing Executing /asterisk/failed_call event callbacks."
+                Events.trigger [:asterisk, :failed_call], failed_call.call
                 call.hangup!
               rescue => e
                 ahn_log.agi.error e
               end
             rescue HungupExtensionCallException => hungup_call
               begin
-                ahn_log.agi "Received \"h\" meta-call. Executing OnHungupCall hooks."
-                Hooks::OnHungupCall.trigger_hooks(hungup_call.call)
+                ahn_log.agi "Received \"h\" meta-call. Executing /asterisk/call_hangup event callbacks."
+                Events.trigger [:asterisk, :call_hangup], hungup_call.call
                 call.hangup!
               rescue => e
                 ahn_log.agi.error e

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

@@ -7,6 +7,22 @@ module Adhearsion
       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.
+        # More information here: http://www.voip-info.org/wiki/index.php?page=Asterisk+variable+DIALSTATUS
+        # 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)
+        #
+        #
         DIAL_STATUSES   = Hash.new(:unknown).merge(:answer      => :answered,
                                                    :congestion  => :congested, 
                                                    :busy        => :busy,
@@ -36,17 +52,47 @@ module Adhearsion
           end
         end
         
+        # This method is the underlying method executed by nearly all the command methods in this module.
+        # It is 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 method you to communicate directly with an Asterisk server via the FAGI protocol.
+        # For more information about FAGI visit: http://www.voip-info.org/wiki/view/Asterisk+FastAGI
         def raw_response(message = nil)
           ahn_log.agi.debug ">>> #{message}"
           write message if message
           read
         end
         
+        # The answer command must be called first before any other commands can be issued.
+        # In typical adhearsion applications the answer command 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 
+        # an answer command has already been issued either explicitly by your code or implicitly
+        # by the standard adhearsion configuration.
         def answer
           raw_response "ANSWER"
           true
         end
         
+        # This asterisk dialplan command allows you to instruct Asterisk to start applications
+        # which are typically run from extensions.conf.  For a complete list of these commands
+        # please visit: http://www.voip-info.org/wiki/view/Asterisk+-+documentation+of+application+commands
+        #
+        # 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 
+        # available through the standard commands provided through FAGI - then you can used EXEC.
+        #
+        # Example:
+        # execute 'SIPAddHeader', '"Call-Info: answer-after=0"
+        # 
+        # Using execute in this way will add a header to an existing SIP call.
+        # 
         def execute(application, *arguments)
           result = raw_response("EXEC #{application} #{arguments * '|'}")
           return false if error?(result)
@@ -54,6 +100,10 @@ module Adhearsion
         end
         
         # Hangs up the current channel.
+        # After this command is issued, your application will stop executing.
+        # This should be used in the same way you would call the ruby exit() method to exit an application.
+        # If it is necessary to do some additional cleanup tasks before returning control back to asterisk, then
+        # make sure you have setup a begin...ensure block in the context of your adhearsion application dialplan.
         def hangup
           raw_response 'HANGUP'
         end
@@ -116,10 +166,12 @@ module Adhearsion
       	  block.call(next_message)
     	  end
 
+        # This command shouled 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
@@ -482,6 +534,10 @@ module Adhearsion
           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)
+        # A complete description is available here: http://www.voip-info.org/wiki/view/get+variable
+        # Use get_variable to pass information from other modules or high level configurations from the asterisk dialplan
+        # to the adhearsion dialplan.
       	def get_variable(variable_name)
       	  result = raw_response("GET VARIABLE #{variable_name}")
       	  case result
@@ -492,6 +548,12 @@ module Adhearsion
     	    end
     	  end
     	  
+    	  # Use set_variable to pass information back to the asterisk dial plan.
+    	  # A complete decription is available here: http://www.voip-info.org/wiki/view/set+variable
+    	  # 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.
     	  def set_variable(variable_name, value)
     	    raw_response("SET VARIABLE %s %p" % [variable_name.to_s, value.to_s]) == "200 result=1"
   	    end
@@ -580,6 +642,42 @@ module Adhearsion
           voicemail_main
         end
         
+        # Use this command to dial an extension i.e. "phone number" in asterisk
+        # This command maps to the Asterisk DIAL command in the asterisk dialplan: http://www.voip-info.org/wiki-Asterisk+cmd+Dial
+        #
+        # The first parameter, number, must be a string that 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.
+        # Examples:
+        #
+        # Make a call to the PSTN using my SIP provider for VoIP termination:
+        # dial("SIP/19095551001@my.sip.voip.terminator.us")
+        # 
+        # 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
+        #
+        # Make a call using the IAX provider to the PSTN 
+        # dial("IAX2/my.id@voipjet/19095551234", :name=>"John Doe", :caller_id=>"9095551234")
+        #
+        # Options Parameter:
+        # :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 visit: http://www.voip-info.org/wiki-Asterisk+cmd+Dial
+        #
+        # :confirm - ?
+        # 
         def dial(number, options={})
           *recognized_options = :caller_id, :name, :for, :options, :confirm
           
@@ -645,13 +743,13 @@ module Adhearsion
             end
             nil
           end
-        
+          
           def set_caller_id_number(caller_id)
             return unless caller_id
             raise ArgumentError, "Caller ID must be numerical" if caller_id.to_s !~ /^\d+$/
             raw_response %(SET CALLERID %p) % caller_id
           end
-
+          
           def set_caller_id_name(caller_id_name)
             return unless caller_id_name
             variable "CALLERID(name)" => caller_id_name