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 collapse

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

Parameters:

  • type (:get, :set, :result, :error, nil) (defaults to: :set) —

    the IQ type

  • node (String) (defaults to: nil) —

    the name of the node

  • action (:cancel, :execute, :complete, :next, :prev, nil) (defaults to: :execute) —

    the command’s action

Returns:

  • (Command) —

    a new Command stanza



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

#action ⇒ Symbol?

Get the action of the command

Returns:

  • (Symbol, nil) 


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

Parameters:

  • action (:cancel, :execute, :complete, :next, :prev) —

    the new action



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

#actions ⇒ Blather::XMPPNode

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

Returns:



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_actions ⇒ Array<Symbol>

Get the command’s allowed actions

Returns:

  • (Array<Symbol>) 


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

Parameters:

  • allowed_actions ([:prev, :next, :complete]) —

    the new allowed actions



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

Returns:

  • (true, false) 


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

Returns:

  • (true, false) 


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

def canceled?
  self.status == :canceled
end

#command ⇒ Blather::XMPPNode

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

Returns:



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

Returns:

  • (true, false) 


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

Returns:

  • (true, false) 


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

Returns:

  • (true, false) 


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

Returns:

  • (true, false) 


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

Returns:

  • (true, false) 


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

def executing?
  self.status == :executing
end

#form ⇒ Object

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

Returns:

  • (true, false) 


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

Returns:

  • (true, false) 


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

def next?
  self.action == :next
end

#node ⇒ String?

Get the name of the node

Returns:

  • (String, nil) 


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

Parameters:

  • node (String, nil) —

    the new node name



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

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

#note ⇒ Blather::XMPPNode

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

Returns:



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_text ⇒ Object

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

Parameters:

  • note_text (String) —

    the command’s new 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_type ⇒ Symbol?

Get the note_type of the command

Returns:

  • (Symbol, nil) 


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

Parameters:

  • note_type (:executing, :completed, :canceled) —

    the new note_type



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

Returns:

  • (true, false) 


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

def prev?
  self.action == :prev
end

#primary_allowed_action ⇒ Symbol

Get the primary allowed action

Returns:

  • (Symbol) 


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

Parameters:

  • a (#to_sym) —

    the primary allowed action



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

Parameters:

  • disallowed_actions ([:prev, :next, :complete]) —

    the allowed actions to remove



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

Parameters:

  • opts (Hash) (defaults to: {}) —

    options to pass to reply!

Options Hash (opts):

  • :remove_children (Boolean) —

    Wether or not to remove child nodes when replying

Returns:

  • (self) 


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

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

#sessionid ⇒ String?

Get the sessionid of the command

Returns:

  • (String, nil) 


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

Parameters:

  • sessionid (String, nil) —

    the new sessionid



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

Returns:

  • (true, false) 


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

def sessionid?
  !sessionid.nil?
end

#status ⇒ Symbol?

Get the status of the command

Returns:

  • (Symbol, nil) 


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

Parameters:

  • status (:executing, :completed, :canceled) —

    the new status



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

Returns:

  • (true, false) 


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

def warn?
  self.status == :warn
end