Class: Jabber::Presence

Inherits:
XMPPStanza show all
Includes:
Comparable, XParent
Defined in:
lib/xmpp4r/presence.rb

Overview

The presence class is used to construct presence messages to send to the Jabber service.

Constant Summary collapse

PRESENCE_STATUS =

Compare two presences. The most suitable to talk with is the biggest.

{ :chat => 4,
nil => 3,
:dnd => 2,
:away => 1,
:xa => 0,
:unavailable => -1,
:error => -2 }

Instance Method Summary collapse

Methods included from XParent

#x

Methods inherited from XMPPStanza

answer, #answer, #error, #from, #from=, #id, #id=, #normalize, #set_from, #set_id, #set_to, #to, #to=

Methods inherited from XMPPElement

class_for_name_xmlns, #clone, force_xmlns, force_xmlns?, import, name_xmlns, name_xmlns_for_class, #parent=, #set_xml_lang, #typed_add, #xml_lang, #xml_lang=

Methods inherited from REXML::Element

#==, #delete_elements, #each_elements, #first_element, #first_element_content, #first_element_text, #import, import, #replace_element_content, #replace_element_text, #typed_add

Constructor Details

#initialize(show = nil, status = nil, priority = nil) ⇒ Presence

Create presence stanza

show
Symbol

Initial Availability Status (see show)

status
String

Initial status message

priority
Fixnum

Initial priority value



24
25
26
27
28
29
 
# File 'lib/xmpp4r/presence.rb', line 24

def initialize(show=nil, status=nil, priority=nil)
  super()
  set_show(show) if show
  set_status(status) if status
  set_priority(priority) if priority
end

Instance Method Details

#<=>(o) ⇒ Object

Compare two presences using priority (with cmp_interest as fall-back).



197
198
199
200
201
202
203
 
# File 'lib/xmpp4r/presence.rb', line 197

def <=>(o)
  if priority.to_i == o.priority.to_i
    cmp_interest(o)
  else
    priority.to_i <=> o.priority.to_i
  end
end

#cmp_interest(o) ⇒ Object 



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/xmpp4r/presence.rb', line 215

def cmp_interest(o)
  if type.nil?
    if o.type.nil?
      # both available.
      PRESENCE_STATUS[show] <=> PRESENCE_STATUS[o.show]
    else
      return -1
    end
  elsif o.type.nil?
    return 1
  else
    # both are non-nil. We consider this is equal.
    return 0
  end
end

#priority ⇒ Object

Get presence priority, or nil if absent

result
Integer 


163
164
165
166
167
168
169
170
 
# File 'lib/xmpp4r/presence.rb', line 163

def priority
   e = first_element_text('priority')
  if e
    return e.to_i
  else
    return nil
  end
end

#priority=(val) ⇒ Object

Set presence priority

val
Integer

Priority value between -128 and +127

Warning: negative values make you receive no subscription requests etc. (RFC3921 - 2.2.2.3.)



178
179
180
181
182
183
184
 
# File 'lib/xmpp4r/presence.rb', line 178

def priority=(val)
  if val.nil?
    delete_element('priority')
  else
    replace_element_text('priority', val)
  end
end

#set_priority(val) ⇒ Object

Set presence priority (chaining-friendly)

val
Integer

Priority value between -128 and +127



189
190
191
192
 
# File 'lib/xmpp4r/presence.rb', line 189

def set_priority(val)
  self.priority = val
  self
end

#set_show(val) ⇒ Object

Set Availability Status (chaining-friendly)

val
Symbol

or [Nil] See show for explanation



129
130
131
132
 
# File 'lib/xmpp4r/presence.rb', line 129

def set_show(val)
  self.show = val
  self
end

#set_status(val) ⇒ Object

Set status message (chaining-friendly)

val
String

or nil



155
156
157
158
 
# File 'lib/xmpp4r/presence.rb', line 155

def set_status(val)
  self.status = val
  self
end

#set_type(val) ⇒ Object

Set type of presence (chaining-friendly)

val
Symbol

See type for possible subscription types



76
77
78
79
 
# File 'lib/xmpp4r/presence.rb', line 76

def set_type(val)
  self.type = val
  self
end

#show ⇒ Object

Get Availability Status (RFC3921 - 5.2)

result
Symbol

or [Nil] Valid values according to RFC3921:

  • nil (Available, no <show/> element)

  • :away

  • :chat (Free for chat)

  • :dnd (Do not disturb)

  • :xa (Extended away)



89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/xmpp4r/presence.rb', line 89

def show
  e = first_element('show')
  text = e ? e.text : nil
  case text
    when 'away' then :away
    when 'chat' then :chat
    when 'dnd' then :dnd
    when 'xa' then :xa
    else nil
  end
end

#show=(val) ⇒ Object

Set Availability Status

val
Symbol

or [Nil] See show for explanation



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/xmpp4r/presence.rb', line 104

def show=(val)
  xe = first_element('show')
  if xe.nil?
    xe = add_element('show')
  end
  case val
    when String then raise "Invalid value for show."
    when :away then text = 'away'
    when :chat then text = 'chat'
    when :dnd then text = 'dnd'
    when :xa then text = 'xa'
    when nil then text = nil
    else raise "Invalid value for show."
  end

  if text.nil?
    delete_element(xe)
  else
    xe.text = text
  end
end

#status ⇒ Object

Get status message

result
String

or nil



137
138
139
 
# File 'lib/xmpp4r/presence.rb', line 137

def status
  first_element_text('status')
end

#status=(val) ⇒ Object

Set status message

val
String

or nil



144
145
146
147
148
149
150
 
# File 'lib/xmpp4r/presence.rb', line 144

def status=(val)
  if val.nil?
    delete_element('status')
  else
    replace_element_text('status', val)
  end
end

#type ⇒ Object

Get type of presence

result
Symbol

or [Nil] Possible values are:

  • :error

  • :probe (Servers send this to request presence information)

  • :subscribe (Subscription request)

  • :subscribed (Subscription approval)

  • :unavailable (User has gone offline)

  • :unsubscribe (Unsubscription request)

  • :unsubscribed (Unsubscription approval)

  • nil

    (available)

See RFC3921 - 2.2.1. for explanation.



44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/xmpp4r/presence.rb', line 44

def type
  case super
    when 'error' then :error
    when 'probe' then :probe
    when 'subscribe' then :subscribe
    when 'subscribed' then :subscribed
    when 'unavailable' then :unavailable
    when 'unsubscribe' then :unsubscribe
    when 'unsubscribed' then :unsubscribed
    else nil
  end
end

#type=(val) ⇒ Object

Set type of presence

val
Symbol

See type for possible subscription types



60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/xmpp4r/presence.rb', line 60

def type=(val)
  case val
    when :error then super('error')
    when :probe then super('probe')
    when :subscribe then super('subscribe')
    when :subscribed then super('subscribed')
    when :unavailable then super('unavailable')
    when :unsubscribe then super('unsubscribe')
    when :unsubscribed then super('unsubscribed')
    else super(nil)
  end
end