class Blather::Stanza::Iq
[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
@handler :iq
Constants
- VALID_TYPES
@private
Public Class Methods
@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
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
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
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
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
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]
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
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
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
Ensures type is :get, :set, :result or :error
@param [#to_sym] type the Iq
type. Must be one of VALID_TYPES
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