Class: Blather::Stanza::Iq::Command

Inherits:
Blather::Stanza::Iq show all
Defined in:
lib/blather/stanza/iq/command.rb

Overview

# Command Stanza

[XEP-0050 Ad-Hoc Commands](xmpp.org/extensions/xep-0050.html)

This is a base class for any command based Iq stanzas. It provides a base set of methods for working with command stanzas

Constant Summary

VALID_ACTIONS =
[:cancel, :execute, :complete, :next, :prev].freeze
VALID_STATUS =
[:executing, :completed, :canceled].freeze
VALID_NOTE_TYPES =
[:info, :warn, :error].freeze

Constants inherited from Blather::Stanza::Iq

VALID_TYPES

Constants inherited from XMPPNode

XMPPNode::BASE_NAMES

Instance Attribute Summary

Attributes inherited from Blather::Stanza

#handler_hierarchy

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Blather::Stanza::Iq

#get?, import, #result?, #set?, #type=

Methods inherited from Blather::Stanza

#as_error, #from, #from=, handler_list, #id, #id=, #initialize, next_id, register, #reply, #to, #to=, #type, #type=

Methods inherited from XMPPNode

class_from_registration, #decorate, decorator_modules, import, parse, register, #to_stanza

Constructor Details

This class inherits a constructor from Blather::Stanza

Class Method Details

.new(type = :set, node = nil, action = :execute) ⇒ Command

Overrides the parent method to ensure a command node is created



29
30
31
32
33
34
35
# File 'lib/blather/stanza/iq/command.rb', line 29

def self.new(type = :set, node = nil, action = :execute)
  new_node = super type
  new_node.command
  new_node.node = node
  new_node.action = action
  new_node
end

Instance Method Details

#actionSymbol?

Get the action of the command



122
123
124
# File 'lib/blather/stanza/iq/command.rb', line 122

def action
  (val = command[:action]) && val.to_sym
end

#action=(action) ⇒ Object

Set the action of the command



164
165
166
167
168
169
# File 'lib/blather/stanza/iq/command.rb', line 164

def action=(action)
  if action && !VALID_ACTIONS.include?(action.to_sym)
    raise ArgumentError, "Invalid Action (#{action}), use: #{VALID_ACTIONS*' '}"
  end
  command[:action] = action
end

#actionsBlather::XMPPNode

Command actions accessor If a command actions element exists it will be returned. Otherwise a new actions element will be created and returned



214
215
216
217
218
219
220
# File 'lib/blather/stanza/iq/command.rb', line 214

def actions
  unless a = self.command.find_first('ns:actions', :ns => self.class.registered_ns)
    (self.command << (a = XMPPNode.new('actions', self.document)))
    a.namespace = self.command.namespace
  end
  a
end

#allowed_actionsArray<Symbol>

Get the command's allowed actions



225
226
227
# File 'lib/blather/stanza/iq/command.rb', line 225

def allowed_actions
  ([:execute] + actions.children.map { |action| action.name.to_sym }).uniq
end

#allowed_actions=(allowed_actions) ⇒ Object

Add allowed actions to the command



252
253
254
255
256
257
258
259
# File 'lib/blather/stanza/iq/command.rb', line 252

def allowed_actions=(allowed_actions)
  allowed_actions = ([allowed_actions].flatten.map(&:to_sym) + [:execute]).uniq
  if (invalid_actions = allowed_actions - VALID_ACTIONS).size > 0
    raise ArgumentError, "Invalid Action(s) (#{invalid_actions*' '}), use: #{VALID_ACTIONS*' '}"
  end
  actions.children.map(&:remove)
  allowed_actions.each { |action| actions << XMPPNode.new(action.to_s) }
end

#cancel?true, false

Check if the command action is :cancel



129
130
131
# File 'lib/blather/stanza/iq/command.rb', line 129

def cancel?
  self.action == :cancel
end

#canceled?true, false

Check if the command status is :canceled



195
196
197
# File 'lib/blather/stanza/iq/command.rb', line 195

def canceled?
  self.status == :canceled
end

#commandBlather::XMPPNode

Command node accessor If a command node exists it will be returned. Otherwise a new node will be created and returned



65
66
67
68
69
70
71
72
73
74
75
76
77
# File 'lib/blather/stanza/iq/command.rb', line 65

def command
  c = if self.class.registered_ns
    find_first('ns:command', :ns => self.class.registered_ns)
  else
    find_first('command')
  end

  unless c
    (self << (c = XMPPNode.new('command', self.document)))
    c.namespace = self.class.registered_ns
  end
  c
end

#complete?true, false

Check if the command action is :complete



143
144
145
# File 'lib/blather/stanza/iq/command.rb', line 143

def complete?
  self.action == :complete
end

#completed?true, false

Check if the command status is :completed



188
189
190
# File 'lib/blather/stanza/iq/command.rb', line 188

def completed?
  self.status == :completed
end

#error?true, false

Check if the command status is :error



305
306
307
# File 'lib/blather/stanza/iq/command.rb', line 305

def error?
  self.status == :error
end

#execute?true, false

Check if the command action is :execute



136
137
138
# File 'lib/blather/stanza/iq/command.rb', line 136

def execute?
  self.action == :execute
end

#executing?true, false

Check if the command status is :executing



181
182
183
# File 'lib/blather/stanza/iq/command.rb', line 181

def executing?
  self.status == :executing
end

#formObject

Returns the command's x:data form child



332
333
334
# File 'lib/blather/stanza/iq/command.rb', line 332

def form
  X.find_or_create command
end

#info?true, false

Check if the command status is :info



291
292
293
# File 'lib/blather/stanza/iq/command.rb', line 291

def info?
  self.note_type == :info
end

#inherit(node) ⇒ Object

Overrides the parent method to ensure the current command node is destroyed and the action is set to execute if no action provided

See Also:

  • Blather::Stanza::Iq#inherit


41
42
43
44
45
46
# File 'lib/blather/stanza/iq/command.rb', line 41

def inherit(node)
  command.remove
  super
  self.action = :execute unless self.action
  self
end

#new_sessionid!Object

Generate a new session ID (SHA-1 hash)



115
116
117
# File 'lib/blather/stanza/iq/command.rb', line 115

def new_sessionid!
  self.sessionid = "commandsession-#{id}"
end

#next?true, false

Check if the command action is :next



150
151
152
# File 'lib/blather/stanza/iq/command.rb', line 150

def next?
  self.action == :next
end

#nodeString?

Get the name of the node



82
83
84
# File 'lib/blather/stanza/iq/command.rb', line 82

def node
  command[:node]
end

#node=(node) ⇒ Object

Set the name of the node



89
90
91
# File 'lib/blather/stanza/iq/command.rb', line 89

def node=(node)
  command[:node] = node
end

#noteBlather::XMPPNode

Command note accessor If a command note exists it will be returned. Otherwise a new note will be created and returned



273
274
275
276
277
278
279
# File 'lib/blather/stanza/iq/command.rb', line 273

def note
  unless n = self.command.find_first('ns:note', :ns => self.class.registered_ns)
    (self.command << (n = XMPPNode.new('note', self.document)))
    n.namespace = self.command.namespace
  end
  n
end

#note_textObject

Get the text of the command's note



320
321
322
# File 'lib/blather/stanza/iq/command.rb', line 320

def note_text
  content_from :note
end

#note_text=(note_text) ⇒ Object

Set the command's note text



327
328
329
# File 'lib/blather/stanza/iq/command.rb', line 327

def note_text=(note_text)
  set_content_for :note, note_text
end

#note_typeSymbol?

Get the note_type of the command



284
285
286
# File 'lib/blather/stanza/iq/command.rb', line 284

def note_type
  (val = note[:type]) && val.to_sym
end

#note_type=(note_type) ⇒ Object

Set the note_type of the command



312
313
314
315
316
317
# File 'lib/blather/stanza/iq/command.rb', line 312

def note_type=(note_type)
  if note_type && !VALID_NOTE_TYPES.include?(note_type.to_sym)
    raise ArgumentError, "Invalid Action (#{note_type}), use: #{VALID_NOTE_TYPES*' '}"
  end
  note[:type] = note_type
end

#prev?true, false

Check if the command action is :prev



157
158
159
# File 'lib/blather/stanza/iq/command.rb', line 157

def prev?
  self.action == :prev
end

#primary_allowed_actionSymbol

Get the primary allowed action



232
233
234
# File 'lib/blather/stanza/iq/command.rb', line 232

def primary_allowed_action
  (actions[:execute] || :execute).to_sym
end

#primary_allowed_action=(a) ⇒ Object

Set the primary allowed action

This must be one of :prev, :next, :complete or :execute



241
242
243
244
245
246
247
# File 'lib/blather/stanza/iq/command.rb', line 241

def primary_allowed_action=(a)
  a = a.to_sym
  if a && ![:prev, :next, :complete, :execute].include?(a)
    raise ArgumentError, "Invalid Action (#{a}), use: #{[:prev, :next, :complete, :execute]*' '}"
  end
  actions[:execute] = a
end

#remove_allowed_actions!Object

Remove allowed actions from the command



264
265
266
# File 'lib/blather/stanza/iq/command.rb', line 264

def remove_allowed_actions!
  actions.remove
end

#reply!(opts = {}) ⇒ self

Overrides the parent method to ensure the reply has no action

Options Hash (opts):

  • :remove_children (Boolean)

    Wether or not to remove child nodes when replying



54
55
56
57
58
# File 'lib/blather/stanza/iq/command.rb', line 54

def reply!(opts = {})
  super
  self.action = nil
  self
end

#sessionidString?

Get the sessionid of the command



96
97
98
# File 'lib/blather/stanza/iq/command.rb', line 96

def sessionid
  command[:sessionid]
end

#sessionid=(sessionid) ⇒ Object

Set the sessionid of the command



110
111
112
# File 'lib/blather/stanza/iq/command.rb', line 110

def sessionid=(sessionid)
  command[:sessionid] = Digest::SHA1.hexdigest(sessionid)
end

#sessionid?true, false

Check if there is a sessionid set



103
104
105
# File 'lib/blather/stanza/iq/command.rb', line 103

def sessionid?
  !sessionid.nil?
end

#statusSymbol?

Get the status of the command



174
175
176
# File 'lib/blather/stanza/iq/command.rb', line 174

def status
  ((val = command[:status]) && val.to_sym) || :executing
end

#status=(status) ⇒ Object

Set the status of the command



202
203
204
205
206
207
# File 'lib/blather/stanza/iq/command.rb', line 202

def status=(status)
  if status && !VALID_STATUS.include?(status.to_sym)
    raise ArgumentError, "Invalid Action (#{status}), use: #{VALID_STATUS*' '}"
  end
  command[:status] = status
end

#warn?true, false

Check if the command status is :warn



298
299
300
# File 'lib/blather/stanza/iq/command.rb', line 298

def warn?
  self.status == :warn
end