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

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=, next_id, register, #reply, #to, #to=, #type, #type=

Methods inherited from XMPPNode

class_from_registration, #content_from, import, #inherit_attrs, #inspect, #namespace=, #namespace_href, #nokogiri_namespace=, #read_attr, #read_content, register, #remove_child, #remove_children, #set_content_for, #to_stanza, #write_attr

Methods inherited from Nokogiri::XML::Node

#[]=, #attr_set, #find_first, #nokogiri_xpath, #xpath

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



26
27
28
29
30
31
32
 
# File 'lib/blather/stanza/iq/command.rb', line 26

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) 


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

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



158
159
160
161
162
163
 
# File 'lib/blather/stanza/iq/command.rb', line 158

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:



208
209
210
211
212
213
214
 
# File 'lib/blather/stanza/iq/command.rb', line 208

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 ⇒ [Symbol]

Get the command’s allowed actions

Returns:

  • ([Symbol]) 


219
220
221
 
# File 'lib/blather/stanza/iq/command.rb', line 219

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



237
238
239
240
241
242
243
244
 
# File 'lib/blather/stanza/iq/command.rb', line 237

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) 


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

def cancel?
  self.action == :cancel
end

#canceled? ⇒ true, false

Check if the command status is :canceled

Returns:

  • (true, false) 


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

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:



59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/blather/stanza/iq/command.rb', line 59

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) 


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

def complete?
  self.action == :complete
end

#completed? ⇒ true, false

Check if the command status is :completed

Returns:

  • (true, false) 


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

def completed?
  self.status == :completed
end

#error? ⇒ true, false

Check if the command status is :error

Returns:

  • (true, false) 


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

def error?
  self.status == :error
end

#execute? ⇒ true, false

Check if the command action is :execute

Returns:

  • (true, false) 


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

def execute?
  self.action == :execute
end

#executing? ⇒ true, false

Check if the command status is :executing

Returns:

  • (true, false) 


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

def executing?
  self.status == :executing
end

#form ⇒ Object

Returns the command’s x:data form child



317
318
319
 
# File 'lib/blather/stanza/iq/command.rb', line 317

def form
  X.find_or_create command
end

#info? ⇒ true, false

Check if the command status is :info

Returns:

  • (true, false) 


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

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


38
39
40
41
42
43
 
# File 'lib/blather/stanza/iq/command.rb', line 38

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)



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

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

#next? ⇒ true, false

Check if the command action is :next

Returns:

  • (true, false) 


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

def next?
  self.action == :next
end

#node ⇒ String?

Get the name of the node

Returns:

  • (String, nil) 


76
77
78
 
# File 'lib/blather/stanza/iq/command.rb', line 76

def node
  command[:node]
end

#node=(node) ⇒ Object

Set the name of the node

Parameters:

  • node (String, nil) —

    the new node name



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

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:



258
259
260
261
262
263
264
 
# File 'lib/blather/stanza/iq/command.rb', line 258

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



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

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



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

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) 


269
270
271
 
# File 'lib/blather/stanza/iq/command.rb', line 269

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



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

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) 


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

def prev?
  self.action == :prev
end

#primary_allowed_action ⇒ Object 



223
224
225
 
# File 'lib/blather/stanza/iq/command.rb', line 223

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

#primary_allowed_action=(a) ⇒ Object 



227
228
229
230
231
232
 
# File 'lib/blather/stanza/iq/command.rb', line 227

def primary_allowed_action=(a)
  if a && ![:prev, :next, :complete, :execute].include?(a.to_sym)
    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



249
250
251
 
# File 'lib/blather/stanza/iq/command.rb', line 249

def remove_allowed_actions!
  actions.remove
end

#reply! ⇒ self

Overrides the parent method to ensure the reply has no action

Returns:

  • (self) 


48
49
50
51
52
 
# File 'lib/blather/stanza/iq/command.rb', line 48

def reply!
  super
  self.action = nil
  self
end

#sessionid ⇒ String?

Get the sessionid of the command

Returns:

  • (String, nil) 


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

def sessionid
  command[:sessionid]
end

#sessionid=(sessionid) ⇒ Object

Set the sessionid of the command

Parameters:

  • sessionid (String, nil) —

    the new sessionid



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

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

#sessionid? ⇒ true, false

Check if there is a sessionid set

Returns:

  • (true, false) 


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

def sessionid?
  !sessionid.nil?
end

#status ⇒ Symbol?

Get the status of the command

Returns:

  • (Symbol, nil) 


168
169
170
 
# File 'lib/blather/stanza/iq/command.rb', line 168

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



196
197
198
199
200
201
 
# File 'lib/blather/stanza/iq/command.rb', line 196

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) 


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

def warn?
  self.status == :warn
end