Class: RubyAMI::Action

Inherits:
Object show all
Defined in:
lib/ruby_ami/action.rb

Defined Under Namespace

Classes: UnsupportedActionName

Constant Summary

CAUSAL_EVENT_NAMES =
%w[queuestatus sippeers iaxpeers parkedcalls dahdishowchannels coreshowchannels
dbget status agents konferencelist]

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Action) initialize(name, headers = {}, &block)

Returns a new instance of Action



10
11
12
13
14
15
16
17
18
19
# File 'lib/ruby_ami/action.rb', line 10

def initialize(name, headers = {}, &block)
  @name       = name.to_s.downcase.freeze
  @headers    = headers.stringify_keys.freeze
  @action_id  = UUIDTools::UUID.random_create.to_s
  @response   = FutureResource.new
  @response_callback = block
  @state      = :new
  @events     = []
  @event_lock = Mutex.new
end

Instance Attribute Details

- (Object) action_id (readonly)

Returns the value of attribute action_id



3
4
5
# File 'lib/ruby_ami/action.rb', line 3

def action_id
  @action_id
end

- (Object) headers (readonly)

Returns the value of attribute headers



3
4
5
# File 'lib/ruby_ami/action.rb', line 3

def headers
  @headers
end

- (Object) name (readonly)

Returns the value of attribute name



3
4
5
# File 'lib/ruby_ami/action.rb', line 3

def name
  @name
end

- (Object) state

Returns the value of attribute state



5
6
7
# File 'lib/ruby_ami/action.rb', line 5

def state
  @state
end

Instance Method Details

- (Object) <<(message)



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
# File 'lib/ruby_ami/action.rb', line 93

def <<(message)
  case message
  when Error
    self.response = message
  when Event
    raise StandardError, 'This action should not trigger events. Maybe it is now a causal action? This is most likely a bug in RubyAMI' unless has_causal_events?
    @event_lock.synchronize do
      @events << message
    end
    self.response = @pending_response if message.name.downcase == causal_event_terminator_name
  when Response
    if has_causal_events?
      @pending_response = message
    else
      self.response = message
    end
  end
end

- (String) causal_event_terminator_name

Used to determine the event name for an action which has causal events.

Parameters:

  • action_name (String)

Returns:

  • (String)

    The corresponding event name which signals the completion of the causal event sequence.



51
52
53
54
55
56
57
58
59
60
61
62
63
# File 'lib/ruby_ami/action.rb', line 51

def causal_event_terminator_name
  return unless has_causal_events?
  case name
  when "sippeers", "iaxpeers"
    "peerlistcomplete"
  when "dbget"
    "dbgetresponse"
  when "konferencelist"
    "conferencelistcomplete"
  else
    name + "complete"
  end
end

- (Boolean) eql?(other) Also known as: ==

Returns:

  • (Boolean)


118
119
120
# File 'lib/ruby_ami/action.rb', line 118

def eql?(other)
  to_s == other.to_s
end

- (Object) events



112
113
114
115
116
# File 'lib/ruby_ami/action.rb', line 112

def events
  @event_lock.synchronize do
    @events.dup
  end
end

- (String) has_causal_events?

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.

Parameters:

  • name (String)

    the name of the event

  • the (Hash)

    headers associated with this event

Returns:

  • (String)

    the downcase()'d name of the event name for which to wait



41
42
43
# File 'lib/ruby_ami/action.rb', line 41

def has_causal_events?
  CAUSAL_EVENT_NAMES.include? name
end

- (Boolean) replies_with_action_id?

Returns:

  • (Boolean)


25
26
27
# File 'lib/ruby_ami/action.rb', line 25

def replies_with_action_id?
  !UnsupportedActionName::UNSUPPORTED_ACTION_NAMES.include? name
end

- (Object) response(timeout = nil)

If the response has simply not been received yet from Asterisk, the calling Thread will block until it comes in. Once the response comes in, subsequent calls immediately return a reference to the ManagerInterfaceResponse object.



81
82
83
84
85
# File 'lib/ruby_ami/action.rb', line 81

def response(timeout = nil)
  @response.resource(timeout).tap do |resp|
    raise resp if resp.is_a? Exception
  end
end

- (Object) response=(other)



87
88
89
90
91
# File 'lib/ruby_ami/action.rb', line 87

def response=(other)
  @state = :complete
  @response.resource = other
  @response_callback.call other if @response_callback
end

- (Object) to_s

Converts this action into a protocol-valid String, ready to be sent over a socket.



68
69
70
71
72
73
74
# File 'lib/ruby_ami/action.rb', line 68

def to_s
  @textual_representation ||= (
      "Action: #{@name}\r\nActionID: #{@action_id}\r\n" +
      @headers.map { |(key,value)| "#{key}: #{value}" }.join("\r\n") +
      (@headers.any? ? "\r\n\r\n" : "\r\n")
  )
end