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

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

Overview

# Status Stanza

[RFC 3921 Section 2.2.2 - Presence Child Elements](xmpp.org/rfcs/rfc3921.html#rfc.section.2.2.2)

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 = 
[:away, :chat, :dnd, :xa].freeze

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

#error?, import, #probe?, #subscribe?, #subscribed?, #unavailable?, #unsubscribe?, #unsubscribed?

Methods inherited from Blather::Stanza

#as_error, #error?, #from, #from=, handler_list, #id, #id=, next_id, register, #reply, #reply!, #to, #to=, #type

Methods inherited from XMPPNode

class_from_registration, #content_from, import, #inherit, #inherit_attrs, #inspect, #namespace=, #namespace_href, #nokogiri_namespace=, #read_attr, #read_content, register, #remove_child, #remove_children, #set_content_for, #to_stanza, #write_attr

Methods inherited from Nokogiri::XML::Node

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

Class Method Details

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

Create a new Status stanza

Parameters:

  • state (<:away, :chat, :dnd, :xa>) (defaults to: nil) —

    the state of the status

  • message (#to_s) (defaults to: nil) —

    a message to send with the status



88
89
90
91
92
93
 
# File 'lib/blather/stanza/presence/status.rb', line 88

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

Instance Method Details

#<=>(o) ⇒ true, false

Compare status based on priority and state: unavailable status is always less valuable than others Raises an error if the JIDs aren’t the same

Parameters:

Returns:

  • (true, false) 


202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/blather/stanza/presence/status.rb', line 202

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

  if (self.type.nil? && o.type.nil?) || (!self.type.nil? && !o.type.nil?)
    self.priority <=> o.priority
  elsif self.type.nil? && !o.type.nil?
    1
  elsif !self.type.nil? && o.type.nil?
    -1
  end
end

#available? ⇒ true, false

Check if the state is available

Returns:

  • (true, false) 


98
99
100
 
# File 'lib/blather/stanza/presence/status.rb', line 98

def available?
  self.state == :available
end

#away? ⇒ true, false

Check if the state is away

Returns:

  • (true, false) 


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

def away?
  self.state == :away
end

#chat? ⇒ true, false

Check if the state is chat

Returns:

  • (true, false) 


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

def chat?
  self.state == :chat
end

#dnd? ⇒ true, false

Check if the state is dnd

Returns:

  • (true, false) 


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

def dnd?
  self.state == :dnd
end

#message ⇒ String?

Get the status message

Returns:

  • (String, nil) 


185
186
187
 
# File 'lib/blather/stanza/presence/status.rb', line 185

def message
  read_content :status
end

#message=(message) ⇒ Object

Set the status message

Parameters:

  • message (String, nil) 


192
193
194
 
# File 'lib/blather/stanza/presence/status.rb', line 192

def message=(message)
  set_content_for :status, message
end

#priority ⇒ Fixnum<-128...127>

Get the priority of the status

Returns:

  • (Fixnum<-128...127>) 


178
179
180
 
# File 'lib/blather/stanza/presence/status.rb', line 178

def priority
  read_content(:priority).to_i
end

#priority=(new_priority) ⇒ Object

Set the priority of the status Ensures priority is between -128 and 127

Parameters:

  • new_priority (Fixnum<-128...127>) 


168
169
170
171
172
173
 
# File 'lib/blather/stanza/presence/status.rb', line 168

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

#state ⇒ <:available, :away, :chat, :dnd, :xa>

Get the state of the status

Returns:

  • (<:available, :away, :chat, :dnd, :xa>) 


158
159
160
161
162
 
# File 'lib/blather/stanza/presence/status.rb', line 158

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

#state=(state) ⇒ Object

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

Parameters:

  • state (<:available, :away, :chat, :dnd, :xa, nil>) 


145
146
147
148
149
150
151
152
153
 
# File 'lib/blather/stanza/presence/status.rb', line 145

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

  set_content_for :show, state
end

#type=(type) ⇒ Object

Set the type attribute Ensures type is nil or :unavailable

Parameters:

  • type (<:unavailable, nil>) —

    the type



134
135
136
137
138
139
 
# File 'lib/blather/stanza/presence/status.rb', line 134

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

#xa? ⇒ true, false

Check if the state is xa

Returns:

  • (true, false) 


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

def xa?
  self.state == :xa
end