Class: Blather::Stanza::Presence

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

Overview

Presence Stanza

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

Status, Subscription

Defined Under Namespace

Classes: Status, Subscription

Constant Summary collapse

VALID_TYPES =

:nodoc:

[:unavailable, :subscribe, :subscribed, :unsubscribe, :unsubscribed, :probe, :error]

Constants inherited from XMPPNode

XMPPNode::BASE_NAMES

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Blather::Stanza

#as_error, attribute_helpers_for, #from, handler_list, next_id, register, #reply, #reply!, #to

Methods inherited from XMPPNode

attribute_accessor, attribute_reader, attribute_writer, class_from_registration, content_attr_accessor, content_attr_reader, content_attr_writer, #content_from, #inherit, #inherit_attrs, #namespace=, #namespace_href, #nokogiri_namespace=, register, #remove_child, #remove_children, #set_content_for, #to_stanza

Methods inherited from Nokogiri::XML::Node

#[]=, #attr_set, #find_first, #nokogiri_xpath, #xpath

Class Method Details

.import(node) ⇒ 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



60
61
62
63
64
65
66
67
 
# File 'lib/blather/stanza/presence.rb', line 60

def self.import(node) # :nodoc:
  klass = case node['type']
  when nil, 'unavailable' then Status
  when /subscribe/        then Subscription
  else self
  end
  klass.new.inherit(node)
end

.new ⇒ Object

Ensure element_name is “presence” for all subclasses



71
72
73
 
# File 'lib/blather/stanza/presence.rb', line 71

def self.new
  super :presence
end

Instance Method Details

#type=(type) ⇒ Object

Ensures type is one of :unavailable, :subscribe, :subscribed, :unsubscribe, :unsubscribed, :probe or :error

Raises:



79
80
81
82
 
# File 'lib/blather/stanza/presence.rb', line 79

def type=(type) # :nodoc:
  raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}" if type && !VALID_TYPES.include?(type.to_sym)
  super
end