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

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

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

- (Symbol?) action

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

- (Object) action=(action)

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

- (Blather::XMPPNode) actions

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

- (Array<Symbol>) allowed_actions

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

- (Object) allowed_actions=(allowed_actions)

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

- (true, false) cancel?

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

- (true, false) canceled?

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

- (Blather::XMPPNode) command

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

- (true, false) complete?

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

- (true, false) completed?

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

- (true, false) error?

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

- (true, false) execute?

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

- (true, false) executing?

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

- (Object) form

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

- (true, false) info?

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

- (Object) inherit(node)

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

- (Object) new_sessionid!

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

- (true, false) next?

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

- (String?) node

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

- (Object) node=(node)

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

- (Blather::XMPPNode) note

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

- (Object) note_text

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

- (Object) note_text=(note_text)

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

- (Symbol?) note_type

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

- (Object) note_type=(note_type)

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

- (true, false) prev?

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

- (Symbol) primary_allowed_action

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

- (Object) primary_allowed_action=(a)

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

- (Object) remove_allowed_actions!

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

- (self) reply!(opts = {})

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

- (String?) sessionid

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

- (Object) sessionid=(sessionid)

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

- (true, false) sessionid?

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

- (Symbol?) status

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

- (Object) status=(status)

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

- (true, false) warn?

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