Class: Adhearsion::VoIP::Asterisk::Manager::ManagerInterface
- Defined in:
- lib/adhearsion/voip/asterisk/manager_interface.rb
Overview
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.
Defined Under Namespace
Classes: AuthenticationFailedException, ManagerInterfaceAction, NotConnectedError, UnsupportedActionName
Constant Summary collapse
- CAUSAL_EVENT_NAMES =
%w[queuestatus sippeers iaxpeers parkedcalls dahdishowchannels coreshowchannels dbget status agents konferencelist]
- RETRY_SLEEP =
5
- DEFAULT_SETTINGS =
{ :host => "localhost", :port => 5038, :username => "admin", :password => "secret", :events => true, :auto_reconnect => true, :event_callback => proc { |event| Events.trigger(%w[asterisk manager_interface], event) } }.freeze
Class Method Summary collapse
-
.causal_event_terminator_name_for(action_name) ⇒ String
Used to determine the event name for an action which has causal events.
- .connect(*args) ⇒ Object
-
.has_causal_events?(name, headers = {}) ⇒ String
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.
- .replies_with_action_id?(name, headers = {}) ⇒ Boolean
Instance Method Summary collapse
- #action_error_received(ami_error) ⇒ Object
- #action_message_received(message) ⇒ Object
- #actions_connection_disconnected ⇒ Object
- #actions_connection_established ⇒ Object
-
#call_and_exec(channel, app, opts = {}) ⇒ Object
call_and_exec allows you to make a call to a channel and then execute an Astersik application on that call.
-
#call_into_context(channel, context, options = {}) ⇒ Object
call_into_context is syntactic sugar for the Asterisk originate command that allows you to launch a call into a particular context.
- #clear_actions_connection ⇒ Object
- #clear_events_connection ⇒ Object
-
#connect! ⇒ Object
Must be called after instantiation.
- #deprecation_warning ⇒ Object
- #disconnect! ⇒ Object
- #dynamic ⇒ Object
- #event_error_received(message) ⇒ Object
-
#event_message_received(event) ⇒ Object
Called only when this ManagerInterface is instantiated with events enabled.
- #events_connection_disconnected ⇒ Object
- #events_connection_established ⇒ Object
-
#hangup(channel) ⇒ Object
hangup terminates a call accepts a channel as the argument full details here: www.voip-info.org/wiki/index.php?page=Asterisk+Manager+API+Action+Hangup.
-
#initialize(options = {}) ⇒ ManagerInterface
constructor
Creates a new Asterisk Manager Interface connection and exposes certain methods to control it.
-
#introduce(caller, callee, opts = {}) ⇒ Object
An introduction connects two endpoints together.
-
#originate(options = {}) ⇒ Object
The originate method launches a call to Asterisk, full details here: www.voip-info.org/tiki-index.php?page=Asterisk+Manager+API+Action+Originate Takes these arguments as a hash:.
-
#ping ⇒ Object
ping sends an action to the Asterisk Manager Interface that returns a pong more details here: www.voip-info.org/wiki/index.php?page=Asterisk+Manager+API+Action+Ping.
-
#send_action_asynchronously(action_name, headers = {}) ⇒ FutureResource
Used to directly send a new action to Asterisk.
-
#send_action_synchronously(*args) ⇒ ManagerInterfaceResponse, ImmediateResponse
(also: #send_action)
Sends an action over the AMI connection and blocks your Thread until the response comes in.
-
#syntax_error_encountered(ignored_chunk) ⇒ Object
Called when our Ragel parser encounters some unexpected syntax from Asterisk.
Constructor Details
#initialize(options = {}) ⇒ ManagerInterface
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.
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 110 def initialize(={}) = @host = [:host] @username = [:username] @password = [:password] @port = [:port] @events = [:events] @auto_reconnect = [:auto_reconnect] @event_callback = [:event_callback] @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 |
Class Method Details
.causal_event_terminator_name_for(action_name) ⇒ String
Used to determine the event name for an action which has causal events.
73 74 75 76 77 78 79 80 81 82 83 84 85 86 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 73 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 "sippeers", "iaxpeers" "peerlistcomplete" when "dbget" "dbgetresponse" when "konferencelist" "conferencelistcomplete" else action_name + "complete" end end |
.connect(*args) ⇒ Object
40 41 42 43 44 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 40 def connect(*args) new(*args).tap do |connection| connection.connect! end end |
.has_causal_events?(name, headers = {}) ⇒ String
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.
63 64 65 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 63 def has_causal_events?(name, headers={}) CAUSAL_EVENT_NAMES.include? name.to_s.downcase end |
.replies_with_action_id?(name, headers = {}) ⇒ Boolean
46 47 48 49 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 46 def replies_with_action_id?(name, headers={}) name = name.to_s.downcase !UnsupportedActionName::UNSUPPORTED_ACTION_NAMES.include? name end |
Instance Method Details
#action_error_received(ami_error) ⇒ Object
193 194 195 196 197 198 199 200 201 202 203 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 193 def action_error_received(ami_error) action_id = ami_error["ActionID"] corresponding_action = 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 |
#action_message_received(message) ⇒ Object
136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 136 def () if .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 # The "DBGet" command is causal, meaning it has an separate # event that contains the data for command's response. However, # unlike other causal commands, AMI does not send a # "DBGetComplete" action indicating the causal event is # finished. This is fixed starting in Asterisk 1.8. if .name.downcase == "dbgetresponse" event_collection << end # If this is the meta-event which signals no more events will follow and the response is complete. if .name.downcase == corresponding_action.causal_event_terminator_name # Wake up the waiting Thread corresponding_action.future_resource.resource = event_collection.freeze # Clear the stored action and event collection @current_action_with_causal_events = nil @event_collection_for_current_action = nil else event_collection << # We have more causal events coming. end else ahn_log.ami.error "Got an unexpected event on actions socket! This AMI command may have a multi-message response. Try making Adhearsion treat it as CAUSAL_EVENT #{.inspect}" end elsif ["ActionID"].nil? # No ActionID! Release the write lock and wake up the waiter else action_id = ["ActionID"] corresponding_action = action_id if corresponding_action .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 = end else ahn_log.ami.error "Received an AMI message with an unrecognized ActionID!! This may be an bug! #{.inspect}" end end end |
#actions_connection_disconnected ⇒ Object
245 246 247 248 249 250 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 245 def actions_connection_disconnected @actions_state = :disconnected ahn_log.ami.error "AMI connection for ACTION disconnected !!!" clear_actions_connection establish_actions_connection if @auto_reconnect end |
#actions_connection_established ⇒ Object
240 241 242 243 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 240 def actions_connection_established @actions_state = :connected start_actions_writer_loop end |
#call_and_exec(channel, app, opts = {}) ⇒ Object
call_and_exec allows you to make a call to a channel and then execute an Astersik application on that call
400 401 402 403 404 405 406 407 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 400 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] args[:variables] = opts[:variables] if opts[:variables] originate args end |
#call_into_context(channel, context, options = {}) ⇒ Object
call_into_context is syntactic sugar for the Asterisk originate command that allows you to launch a call into a particular context. For example:
call_into_context(‘SIP/[email protected]’, ‘my_context’, { :variables => { :session_guid => new_guid }})
413 414 415 416 417 418 419 420 421 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 413 def call_into_context(channel, context, ={}) #deprecation_warning args = {:channel => channel, :context => context} args[:priority] = [:priority] || 1 args[:exten] = [:extension] if [:extension] args[:caller_id] = [:caller_id] if [:caller_id] args[:variables] = [:variables] if [:variables] originate args end |
#clear_actions_connection ⇒ Object
263 264 265 266 267 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 263 def clear_actions_connection stop_actions_writer_loop clear_actions_connection_resources disconnect_actions_connection if @actions_state.equal? :connected end |
#clear_events_connection ⇒ Object
269 270 271 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 269 def clear_events_connection disconnect_events_connection if @events_state.equal? :connected end |
#connect! ⇒ Object
Must be called after instantiation. Also see ManagerInterface::connect().
234 235 236 237 238 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 234 def connect! establish_actions_connection establish_events_connection if @events self end |
#deprecation_warning ⇒ Object
332 333 334 335 336 337 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 332 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 |
#disconnect! ⇒ Object
273 274 275 276 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 273 def disconnect! clear_actions_connection clear_events_connection end |
#dynamic ⇒ Object
278 279 280 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 278 def dynamic # TODO: Return an object which responds to method_missing end |
#event_error_received(message) ⇒ Object
214 215 216 217 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 214 def event_error_received() # Does this ever even occur? ahn_log.ami.error "Hmmm, got an error on the AMI events-only socket! This must be a bug! #{.inspect}" end |
#event_message_received(event) ⇒ Object
Called only when this ManagerInterface is instantiated with events enabled.
208 209 210 211 212 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 208 def (event) return if event.kind_of?(ManagerInterfaceResponse) && event["Message"] == "Authentication accepted" # TODO: convert the event name to a certain namespace. @event_callback.call(event) end |
#events_connection_disconnected ⇒ Object
256 257 258 259 260 261 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 256 def events_connection_disconnected @events_state = :disconnected ahn_log.ami.error "AMI connection for EVENT disconnected !!!" clear_events_connection establish_events_connection if @auto_reconnect end |
#events_connection_established ⇒ Object
252 253 254 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 252 def events_connection_established @events_state = :connected end |
#hangup(channel) ⇒ Object
hangup terminates a call accepts a channel as the argument full details here: www.voip-info.org/wiki/index.php?page=Asterisk+Manager+API+Action+Hangup
393 394 395 396 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 393 def hangup(channel) #deprecation_warning send_action "Hangup", :channel => channel end |
#introduce(caller, callee, opts = {}) ⇒ Object
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.
384 385 386 387 388 389 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 384 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 |
#originate(options = {}) ⇒ Object
The originate method launches a call to Asterisk, full details here: 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/[email protected]’,
:context => 'my_context',
:exten => 's',
:priority => '1' }
362 363 364 365 366 367 368 369 370 371 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 362 def originate(={}) #deprecation_warning = .clone [:callerid] = .delete :caller_id if .has_key? :caller_id [:exten] = .delete :extension if .has_key? :extension if .has_key?(:variables) && [:variables].kind_of?(Hash) [:variable] = .delete(:variables).map {|pair| pair.join('=')}.join(@coreSettings["ArgumentDelimiter"]) end send_action "Originate", end |
#ping ⇒ Object
ping sends an action to the Asterisk Manager Interface that returns a pong more details here: www.voip-info.org/wiki/index.php?page=Asterisk+Manager+API+Action+Ping
326 327 328 329 330 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 326 def ping #deprecation_warning send_action "Ping" true end |
#send_action_asynchronously(action_name, headers = {}) ⇒ FutureResource
Used to directly send a new action to Asterisk. Note: NEVER supply an ActionID; these are handled internally.
289 290 291 292 293 294 295 296 297 298 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 289 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 |
#send_action_synchronously(*args) ⇒ ManagerInterfaceResponse, ImmediateResponse Also known as: send_action
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.
309 310 311 312 313 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 309 def send_action_synchronously(*args) send_action_asynchronously(*args).response.tap do |response| raise response if response.kind_of?(ManagerInterfaceError) end end |
#syntax_error_encountered(ignored_chunk) ⇒ Object
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.
224 225 226 227 |
# File 'lib/adhearsion/voip/asterisk/manager_interface.rb', line 224 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 |