Class: Blather::Stanza::Iq

Inherits:
Blather::Stanza show all
Defined in:
lib/blather/stanza/iq.rb,
lib/blather/stanza/iq/si.rb,
lib/blather/stanza/iq/ibb.rb,
lib/blather/stanza/iq/s5b.rb,
lib/blather/stanza/iq/ping.rb,
lib/blather/stanza/iq/query.rb,
lib/blather/stanza/iq/vcard.rb,
lib/blather/stanza/iq/roster.rb,
lib/blather/stanza/iq/command.rb

Overview

# 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

  • ‘:get` – The stanza is a request for information or requirements.

  • ‘:set` – The stanza provides required data, sets new values, or replaces existing values.

  • ‘:result` – The stanza is a response to a successful get or set request.

  • ‘:error` – An error has occurred regarding processing or delivery of a previously-sent get or set (see Stanza Errors).

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

Direct Known Subclasses

Command, Ibb, Ping, Query, Si, Vcard, PubSub, PubSubOwner

Defined Under Namespace

Classes: Command, Ibb, Ping, Query, Roster, S5b, Si, Vcard

Constant Summary collapse

VALID_TYPES = 
[:get, :set, :result, :error].freeze

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

#as_error, #from, #from=, handler_list, #id, #id=, #initialize, next_id, register, #reply, #to, #to=, #type

Methods inherited from XMPPNode

class_from_registration, #decorate, decorator_modules, parse, register, #to_stanza

Constructor Details

This class inherits a constructor from Blather::Stanza

Class Method Details

.import(node) ⇒ Object 



62
63
64
65
66
67
68
69
70
71
72
73
74
 
# 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) ⇒ Object

Create a new Iq

Parameters:

  • type (Symbol, nil) (defaults to: nil) —

    the type of stanza (:get, :set, :result, :error)

  • jid (Blather::JID, String, nil) —

    the JID of the inteded recipient

  • id (#to_s) (defaults to: nil) —

    the stanza’s ID. Leaving this nil will set the ID to the next unique number



82
83
84
85
86
87
88
 
# 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

Instance Method Details

#error? ⇒ true, false

Check if the IQ is of type :error

Returns:

  • (true, false) 


114
115
116
 
# File 'lib/blather/stanza/iq.rb', line 114

def error?
  self.type == :error
end

#get? ⇒ true, false

Check if the IQ is of type :get

Returns:

  • (true, false) 


93
94
95
 
# File 'lib/blather/stanza/iq.rb', line 93

def get?
  self.type == :get
end

#reply!(opts = {}) ⇒ self

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

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) 


135
136
137
138
139
140
 
# File 'lib/blather/stanza/iq.rb', line 135

def reply!(opts = {})
  opts = {:remove_children => true}.merge opts
  super
  self.type = :result
  self
end

#result? ⇒ true, false

Check if the IQ is of type :result

Returns:

  • (true, false) 


107
108
109
 
# File 'lib/blather/stanza/iq.rb', line 107

def result?
  self.type == :result
end

#set? ⇒ true, false

Check if the IQ is of type :set

Returns:

  • (true, false) 


100
101
102
 
# File 'lib/blather/stanza/iq.rb', line 100

def set?
  self.type == :set
end

#type=(type) ⇒ Object

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

Parameters:

  • type (#to_sym) —

    the Iq type. Must be one of VALID_TYPES



121
122
123
124
125
126
 
# 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