Class: Blather::Stanza::Presence::Status

Inherits:
Blather::Stanza::Presence show all
Includes:
Comparable
Defined in:
lib/blather/stanza/presence/status.rb

Overview

Status Stanza

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.

State Attribute

The state attribute determains the availability of the entity and can be one of the following:

  • :available – The entity or resource is available

  • :away – The entity or resource is temporarily away.

  • :chat – The entity or resource is actively interested in chatting.

  • :dnd – The entity or resource is busy (dnd = “Do Not Disturb”).

  • :xa – The entity or resource is away for an extended period (xa = “eXtended Away”).

Blather provides a helper for each possible state:

Status#available?
Status#away?
Status#chat?
Status#dnd?
Status#xa?

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

status = Status.new
status.state              # => :available
status.available?         # => true
status.state = :away
status.away?              # => true
status.available?         # => false
status
status.state = :invalid   # => RuntimeError

Type Attribute

The type attribute is inherited from Presence, but limits the value to either nil or :unavailable as these are the only types that relate to Status.

Priority Attribute

The priority attribute sets the priority of the status for the entity and must be an integer between -128 and 127.

Message Attribute

The optional message element contains XML character data specifying a natural-language description of availability status. It is normally used in conjunction with the show element to provide a detailed description of an availability state (e.g., “In a meeting”).

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

status = Status.new
status.message            # => nil
status.message = "gone!"
status.message            # => "gone!"

Constant Summary collapse

VALID_STATES =

:nodoc:

[:away, :chat, :dnd, :xa]

Constants inherited from Blather::Stanza::Presence

VALID_TYPES

Constants inherited from XMPPNode

XMPPNode::BASE_NAMES

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Blather::Stanza::Presence

import

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, import, #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

.new(state = nil, message = nil) ⇒ Object 



72
73
74
75
76
77
 
# File 'lib/blather/stanza/presence/status.rb', line 72

def self.new(state = nil, message = nil)
  node = super()
  node.state = state
  node.message = message
  node
end

Instance Method Details

#<=>(o) ⇒ Object

Compare status based on priority raises an error if the JIDs aren’t the same



121
122
123
124
125
126
 
# File 'lib/blather/stanza/presence/status.rb', line 121

def <=>(o)
  unless self.from && o.from && self.from.stripped == o.from.stripped
    raise ArgumentError, "Cannot compare status from different JIDs: #{[self.from, o.from].inspect}"
  end
  self.priority <=> o.priority
end

#priority=(new_priority) ⇒ Object

Ensure priority is between -128 and 127

Raises:



108
109
110
111
112
 
# File 'lib/blather/stanza/presence/status.rb', line 108

def priority=(new_priority) # :nodoc:
  raise ArgumentError, 'Priority must be between -128 and +127' if new_priority && !(-128..127).include?(new_priority.to_i)
  set_content_for :priority, new_priority
  
end

#state ⇒ Object

:available if state is nil



100
101
102
103
104
 
# File 'lib/blather/stanza/presence/status.rb', line 100

def state # :nodoc:
  state = type || content_from(:show)
  state = :available if state.blank?
  state.to_sym
end

#state=(state) ⇒ Object

Ensure state is one of :available, :away, :chat, :dnd, :xa or nil

Raises:



90
91
92
93
94
95
96
 
# File 'lib/blather/stanza/presence/status.rb', line 90

def state=(state) # :nodoc:
  state = state.to_sym if state
  state = nil if state == :available
  raise ArgumentError, "Invalid Status (#{state}), use: #{VALID_STATES*' '}" if state && !VALID_STATES.include?(state)

  set_content_for :show, state
end

#type=(type) ⇒ Object

Ensures type is nil or :unavailable

Raises:



83
84
85
86
 
# File 'lib/blather/stanza/presence/status.rb', line 83

def type=(type) # :nodoc:
  raise ArgumentError, "Invalid type (#{type}). Must be nil or unavailable" if type && type.to_sym != :unavailable
  super
end