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](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:

  • ‘: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