class Blather::Stanza::Iq

# Iq Stanza

[RFC 3920 Section 9.2.3 - IQ Semantics](xmpp.org/rfcs/rfc3920.html#rfc.section.9.2.3)

Info/Query, or IQ, is a request-response mechanism, similar in some ways to HTTP. The semantics of IQ enable an entity to make a request of, and receive a response from, another entity. The data content of the request and response is defined by the namespace declaration of a direct child element of the IQ element, and the interaction is tracked by the requesting entity through use of the 'id' attribute. Thus, IQ interactions follow a common pattern of structured data exchange such as get/result or set/result (although an error may be returned in reply to a request if appropriate).

## “ID” Attribute

Iq Stanzas require the ID attribute be set. Blather will handle this automatically when a new Iq is created.

## “Type” Attribute

Blather provides a helper for each possible type:

Iq#get?
Iq#set?
Iq#result?
Iq#error?

Blather treats the `type` attribute like a normal ruby object attribute providing a getter and setter. The default `type` is `get`.

iq = Iq.new
iq.type               # => :get
iq.get?               # => true
iq.type = :set
iq.set?               # => true
iq.get?               # => false

iq.type = :invalid    # => RuntimeError

@handler :iq

Constants

VALID_TYPES

@private

Public Class Methods

import(node) click to toggle source

@private

# File lib/blather/stanza/iq.rb, line 62
def self.import(node)
  klass = nil
  node.children.detect do |e|
    ns = e.namespace ? e.namespace.href : nil
    klass = class_from_registration(e.element_name, ns)
  end

  if klass && klass != self
    klass.import(node)
  else
    new(node[:type]).inherit(node)
  end
end
new(type = nil, to = nil, id = nil) click to toggle source

Create a new Iq

@param [Symbol, nil] type the type of stanza (:get, :set, :result, :error) @param [Blather::JID, String, nil] jid the JID of the inteded recipient @param [#to_s] id the stanza's ID. Leaving this nil will set the ID to

the next unique number
Calls superclass method Blather::Stanza::new
# File lib/blather/stanza/iq.rb, line 82
def self.new(type = nil, to = nil, id = nil)
  node = super :iq
  node.type = type || :get
  node.to = to
  node.id = id || self.next_id
  node
end

Public Instance Methods

error?() click to toggle source

Check if the IQ is of type :error

@return [true, false]

# File lib/blather/stanza/iq.rb, line 114
def error?
  self.type == :error
end
get?() click to toggle source

Check if the IQ is of type :get

@return [true, false]

# File lib/blather/stanza/iq.rb, line 93
def get?
  self.type == :get
end
reply!(opts = {}) click to toggle source

Overrides the parent method to ensure the reply is of type :result and that all children are removed.

@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#reply!
# File lib/blather/stanza/iq.rb, line 135
def reply!(opts = {})
  opts = {:remove_children => true}.merge opts
  super
  self.type = :result
  self
end
result?() click to toggle source

Check if the IQ is of type :result

@return [true, false]

# File lib/blather/stanza/iq.rb, line 107
def result?
  self.type == :result
end
set?() click to toggle source

Check if the IQ is of type :set

@return [true, false]

# File lib/blather/stanza/iq.rb, line 100
def set?
  self.type == :set
end
type=(type) click to toggle source

Ensures type is :get, :set, :result or :error

@param [#to_sym] type the Iq type. Must be one of VALID_TYPES

Calls superclass method Blather::Stanza#type=
# File lib/blather/stanza/iq.rb, line 121
def type=(type)
  if type && !VALID_TYPES.include?(type.to_sym)
    raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}"
  end
  super
end