Class: Blather::Stanza::Presence

Inherits:
Blather::Stanza show all
Defined in:
lib/blather/stanza/presence.rb,
lib/blather/stanza/presence/c.rb,
lib/blather/stanza/presence/muc.rb,
lib/blather/stanza/presence/status.rb,
lib/blather/stanza/presence/muc_user.rb,
lib/blather/stanza/presence/subscription.rb

Overview

Presence Stanza

RFC 3921 Section 2.2 - Presence Syntax

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:

  • :unavailable -- Signals that the entity is no longer available for communication

  • :subscribe -- The sender wishes to subscribe to the recipient's presence.

  • :subscribed -- The sender has allowed the recipient to receive their presence.

  • :unsubscribe -- The sender is unsubscribing from another entity's presence.

  • :unsubscribed -- The subscription request has been denied or a previously-granted subscription has been cancelled.

  • :probe -- A request for an entity's current presence; should be generated only by a server on behalf of a user.

  • :error -- An error has occurred regarding processing or delivery of a previously-sent presence stanza.

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

Direct Known Subclasses

C, MUCUser, Status, Subscription

Defined Under Namespace

Classes: C, MUC, MUCUser, Status, Subscription

Constant Summary collapse

VALID_TYPES = 
[ :unavailable,
:subscribe,
:subscribed,
:unsubscribe,
:unsubscribed,
:probe,
: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, #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, *decorators) ⇒ Object

Creates a class based on the presence type either a Status or Subscription object is created based on the type attribute. If neither is found it instantiates a Presence object



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/blather/stanza/presence.rb', line 88

def self.import(node, *decorators) # :nodoc:
  node.children.each do |e|
    ns = e.namespace ? e.namespace.href : nil
    klass = class_from_registration e.element_name, ns
    decorators << klass if klass
  end

  case node['type']
  when nil, 'unavailable'
    decorators << Status
  when /subscribe/
    decorators << Subscription
  end

  super node, *decorators
end

.new(*args) ⇒ Object

Ensure element_name is "presence" for all subclasses



106
107
108
 
# File 'lib/blather/stanza/presence.rb', line 106

def self.new(*args)
  super :presence
end

Instance Method Details

#error? ⇒ true, false

Check if the IQ is of type :error

Returns:

  • (true, false) 


155
156
157
 
# File 'lib/blather/stanza/presence.rb', line 155

def error?
  self.type == :error
end

#probe? ⇒ true, false

Check if the IQ is of type :probe

Returns:

  • (true, false) 


148
149
150
 
# File 'lib/blather/stanza/presence.rb', line 148

def probe?
  self.type == :probe
end

#subscribe? ⇒ true, false

Check if the IQ is of type :subscribe

Returns:

  • (true, false) 


120
121
122
 
# File 'lib/blather/stanza/presence.rb', line 120

def subscribe?
  self.type == :subscribe
end

#subscribed? ⇒ true, false

Check if the IQ is of type :subscribed

Returns:

  • (true, false) 


127
128
129
 
# File 'lib/blather/stanza/presence.rb', line 127

def subscribed?
  self.type == :subscribed
end

#type=(type) ⇒ Object

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

Parameters:

  • type (#to_sym) —

    the Presence type. Must be one of VALID_TYPES



162
163
164
165
166
167
 
# 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? ⇒ true, false

Check if the IQ is of type :unavailable

Returns:

  • (true, false) 


113
114
115
 
# File 'lib/blather/stanza/presence.rb', line 113

def unavailable?
  self.type == :unavailable
end

#unsubscribe? ⇒ true, false

Check if the IQ is of type :unsubscribe

Returns:

  • (true, false) 


134
135
136
 
# File 'lib/blather/stanza/presence.rb', line 134

def unsubscribe?
  self.type == :unsubscribe
end

#unsubscribed? ⇒ true, false

Check if the IQ is of type :unsubscribed

Returns:

  • (true, false) 


141
142
143
 
# File 'lib/blather/stanza/presence.rb', line 141

def unsubscribed?
  self.type == :unsubscribed
end