class Blather::Stanza::Iq::Command

# 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

@handler :command

Constants

VALID_ACTIONS

@private

VALID_NOTE_TYPES

@private

VALID_STATUS

@private

Public Class Methods

new(type = :set, node = nil, action = :execute) click to toggle source

Overrides the parent method to ensure a command node is created

@param [:get, :set, :result, :error, nil] type the IQ type @param [String] node the name of the node @param [:cancel, :execute, :complete, :next, :prev, nil] action the command's action @return [Command] a new Command stanza

Calls superclass method Blather::Stanza::Iq::new
# 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

Public Instance Methods

action() click to toggle source

Get the action of the command

@return [Symbol, nil]

# File lib/blather/stanza/iq/command.rb, line 122
def action
  (val = command[:action]) && val.to_sym
end
action=(action) click to toggle source

Set the action of the command

@param [:cancel, :execute, :complete, :next, :prev] action the new action

# 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() click to toggle source

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

@return [Blather::XMPPNode]

# 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() click to toggle source

Get the command's allowed actions

@return [Array<Symbol>]

# 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) click to toggle source

Add allowed actions to the command

@param [[:prev, :next, :complete]] allowed_actions the new allowed actions

# 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?() click to toggle source

Check if the command action is :cancel

@return [true, false]

# File lib/blather/stanza/iq/command.rb, line 129
def cancel?
  self.action == :cancel
end
canceled?() click to toggle source

Check if the command status is :canceled

@return [true, false]

# File lib/blather/stanza/iq/command.rb, line 195
def canceled?
  self.status == :canceled
end
command() click to toggle source

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

@return [Blather::XMPPNode]

# 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?() click to toggle source

Check if the command action is :complete

@return [true, false]

# File lib/blather/stanza/iq/command.rb, line 143
def complete?
  self.action == :complete
end
completed?() click to toggle source

Check if the command status is :completed

@return [true, false]

# File lib/blather/stanza/iq/command.rb, line 188
def completed?
  self.status == :completed
end
error?() click to toggle source

Check if the command status is :error

@return [true, false]

# File lib/blather/stanza/iq/command.rb, line 305
def error?
  self.status == :error
end
execute?() click to toggle source

Check if the command action is :execute

@return [true, false]

# File lib/blather/stanza/iq/command.rb, line 136
def execute?
  self.action == :execute
end
executing?() click to toggle source

Check if the command status is :executing

@return [true, false]

# File lib/blather/stanza/iq/command.rb, line 181
def executing?
  self.status == :executing
end
form() click to toggle source

Returns the command's x:data form child

# File lib/blather/stanza/iq/command.rb, line 332
def form
  X.find_or_create command
end
info?() click to toggle source

Check if the command status is :info

@return [true, false]

# File lib/blather/stanza/iq/command.rb, line 291
def info?
  self.note_type == :info
end
inherit(node) click to toggle source

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

@see Blather::Stanza::Iq#inherit

Calls superclass method
# 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!() click to toggle source

Generate a new session ID (SHA-1 hash)

# File lib/blather/stanza/iq/command.rb, line 115
def new_sessionid!
  self.sessionid = "commandsession-#{id}"
end
next?() click to toggle source

Check if the command action is :next

@return [true, false]

# File lib/blather/stanza/iq/command.rb, line 150
def next?
  self.action == :next
end
node() click to toggle source

Get the name of the node

@return [String, nil]

# File lib/blather/stanza/iq/command.rb, line 82
def node
  command[:node]
end
node=(node) click to toggle source

Set the name of the node

@param [String, nil] node the new node name

# File lib/blather/stanza/iq/command.rb, line 89
def node=(node)
  command[:node] = node
end
note() click to toggle source

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

@return [Blather::XMPPNode]

# 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() click to toggle source

Get the text of the command's note

# File lib/blather/stanza/iq/command.rb, line 320
def note_text
  content_from :note
end
note_text=(note_text) click to toggle source

Set the command's note text

@param [String] note_text the command's new note text

# File lib/blather/stanza/iq/command.rb, line 327
def note_text=(note_text)
  set_content_for :note, note_text
end
note_type() click to toggle source

Get the note_type of the command

@return [Symbol, nil]

# File lib/blather/stanza/iq/command.rb, line 284
def note_type
  (val = note[:type]) && val.to_sym
end
note_type=(note_type) click to toggle source

Set the note_type of the command

@param [:executing, :completed, :canceled] note_type the new note_type

# 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?() click to toggle source

Check if the command action is :prev

@return [true, false]

# File lib/blather/stanza/iq/command.rb, line 157
def prev?
  self.action == :prev
end
primary_allowed_action() click to toggle source

Get the primary allowed action

@return [Symbol]

# File lib/blather/stanza/iq/command.rb, line 232
def primary_allowed_action
  (actions[:execute] || :execute).to_sym
end
primary_allowed_action=(a) click to toggle source

Set the primary allowed action

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

@param [#to_sym] a the primary allowed action

# 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!() click to toggle source

Remove allowed actions from the command

@param [[:prev, :next, :complete]] disallowed_actions the allowed actions to remove

# File lib/blather/stanza/iq/command.rb, line 264
def remove_allowed_actions!
  actions.remove
end
reply!(opts = {}) click to toggle source

Overrides the parent method to ensure the reply has no action

@param [Hash] opts options to pass to reply! @option opts [Boolean] :remove_children Wether or not to remove child nodes when replying

@return [self]

Calls superclass method Blather::Stanza::Iq#reply!
# File lib/blather/stanza/iq/command.rb, line 54
def reply!(opts = {})
  super
  self.action = nil
  self
end
sessionid() click to toggle source

Get the sessionid of the command

@return [String, nil]

# File lib/blather/stanza/iq/command.rb, line 96
def sessionid
  command[:sessionid]
end
sessionid=(sessionid) click to toggle source

Set the sessionid of the command

@param [String, nil] sessionid the new sessionid

# File lib/blather/stanza/iq/command.rb, line 110
def sessionid=(sessionid)
  command[:sessionid] = Digest::SHA1.hexdigest(sessionid)
end
sessionid?() click to toggle source

Check if there is a sessionid set

@return [true, false]

# File lib/blather/stanza/iq/command.rb, line 103
def sessionid?
  !sessionid.nil?
end
status() click to toggle source

Get the status of the command

@return [Symbol, nil]

# File lib/blather/stanza/iq/command.rb, line 174
def status
  ((val = command[:status]) && val.to_sym) || :executing
end
status=(status) click to toggle source

Set the status of the command

@param [:executing, :completed, :canceled] status the new status

# 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?() click to toggle source

Check if the command status is :warn

@return [true, false]

# File lib/blather/stanza/iq/command.rb, line 298
def warn?
  self.status == :warn
end