class Blather::Stanza::Presence

# Presence Stanza

[RFC 3921 Section 2.2 - Presence Syntax](xmpp.org/rfcs/rfc3921.html#stanzas-presence)

Within Blather most of the interaction with Presence stanzas will be through one of its child classes: Status or Subscription.

Presence stanzas are used to express an entity's current network availability (offline or online, along with various sub-states of the latter and optional user-defined descriptive text), and to notify other entities of that availability. Presence stanzas are also used to negotiate and manage subscriptions to the presence of other entities.

## “Type” Attribute

The `type` attribute of a presence stanza is optional. A presence stanza that does not possess a `type` attribute is used to signal to the server that the sender is online and available for communication. If included, the `type` attribute specifies a lack of availability, a request to manage a subscription to another entity's presence, a request for another entity's current presence, or an error related to a previously-sent presence stanza. If included, the `type` attribute must have one of the following values:

Blather provides a helper for each possible type:

Presence#unavailabe?
Presence#unavailable?
Presence#subscribe?
Presence#subscribed?
Presence#unsubscribe?
Presence#unsubscribed?
Presence#probe?
Presence#error?

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

presence = Presence.new
presence.type                # => nil
presence.type = :unavailable
presence.unavailable?        # => true
presence.error?              # => false

presence.type = :invalid   # => RuntimeError

@handler :presence

Constants

VALID_TYPES

@private

Public Class Methods

new(*args) click to toggle source

Ensure element_name is “presence” for all subclasses

Calls superclass method Blather::Stanza::new
# File lib/blather/stanza/presence.rb, line 106
def self.new(*args)
  super :presence
end

Public Instance Methods

error?() click to toggle source

Check if the IQ is of type :error

@return [true, false]

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

Check if the IQ is of type :probe

@return [true, false]

# File lib/blather/stanza/presence.rb, line 148
def probe?
  self.type == :probe
end
subscribe?() click to toggle source

Check if the IQ is of type :subscribe

@return [true, false]

# File lib/blather/stanza/presence.rb, line 120
def subscribe?
  self.type == :subscribe
end
subscribed?() click to toggle source

Check if the IQ is of type :subscribed

@return [true, false]

# File lib/blather/stanza/presence.rb, line 127
def subscribed?
  self.type == :subscribed
end
type=(type) click to toggle source

Ensures type is one of Blather::Stanza::Presence::VALID_TYPES

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

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

Check if the IQ is of type :unavailable

@return [true, false]

# File lib/blather/stanza/presence.rb, line 113
def unavailable?
  self.type == :unavailable
end
unsubscribe?() click to toggle source

Check if the IQ is of type :unsubscribe

@return [true, false]

# File lib/blather/stanza/presence.rb, line 134
def unsubscribe?
  self.type == :unsubscribe
end
unsubscribed?() click to toggle source

Check if the IQ is of type :unsubscribed

@return [true, false]

# File lib/blather/stanza/presence.rb, line 141
def unsubscribed?
  self.type == :unsubscribed
end