Class: Jabber::Presence

Inherits:
XMLStanza show all
Includes:
Comparable
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 }

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from XMLStanza

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

Methods inherited from REXML::Element

#delete_elements, #first_element, #first_element_text, #import, #replace_element_text

Constructor Details

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

Create presence stanza

show
String

Initial Availability Status

status
String

Initial status message

priority
Fixnum

Initial priority value



20
21
22
23
24
25
 
# File 'lib/xmpp4r/presence.rb', line 20

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

Class Method Details

.import(xmlstanza) ⇒ Object

Create a new presence from a stanza

result
Presence

Imported XMLStanza



42
43
44
 
# File 'lib/xmpp4r/presence.rb', line 42

def Presence.import(xmlstanza)
  Presence::new.import(xmlstanza)
end

Instance Method Details

#<=>(o) ⇒ Object

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



224
225
226
227
228
229
230
 
# File 'lib/xmpp4r/presence.rb', line 224

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 



242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/xmpp4r/presence.rb', line 242

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 


190
191
192
193
194
195
196
197
 
# File 'lib/xmpp4r/presence.rb', line 190

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.)



205
206
207
208
209
210
211
 
# File 'lib/xmpp4r/presence.rb', line 205

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



216
217
218
219
 
# File 'lib/xmpp4r/presence.rb', line 216

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



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

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

#set_status(val) ⇒ Object

Set status message (chaining-friendly)

val
String

or nil



182
183
184
185
 
# File 'lib/xmpp4r/presence.rb', line 182

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



91
92
93
94
 
# File 'lib/xmpp4r/presence.rb', line 91

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)



117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/xmpp4r/presence.rb', line 117

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



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/xmpp4r/presence.rb', line 132

def show=(val)
  xe = first_element('show')
  if xe.nil?
    xe = add_element('show')
  end
  case val
    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



164
165
166
 
# File 'lib/xmpp4r/presence.rb', line 164

def status
  first_element_text('status')
end

#status=(val) ⇒ Object

Set status message

val
String

or nil



171
172
173
174
175
176
177
 
# File 'lib/xmpp4r/presence.rb', line 171

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.



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

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



75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/xmpp4r/presence.rb', line 75

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

#typed_add(element) ⇒ Object

Add an element to the presence stanza

  • <x/> elements are converted to [X]

element
REXML::Element

to add



31
32
33
34
35
36
37
 
# File 'lib/xmpp4r/presence.rb', line 31

def typed_add(element)
  if element.kind_of?(REXML::Element) && (element.name == 'x')
    super(X::import(element))
  else
    super(element)
  end
end

#x(namespace = nil) ⇒ Object

Get the first <x/> element in this stanza, or nil if none found.

namespace
String

Optional, find the first <x/> element having this xmlns

result
REXML::Element

or nil



100
101
102
103
104
105
106
107
 
# File 'lib/xmpp4r/presence.rb', line 100

def x(namespace=nil)
  each_element('x') { |x|
    if namespace.nil? or namespace == x.namespace
      return x
    end
  }
  nil
end