Class Jabber::Presence
In: lib/xmpp4r/presence.rb
Parent: XMLStanza

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

Methods

<=>   cmp_interest   import   new   priority   priority=   set_priority   set_show   set_status   set_type   show   show=   status   status=   type   type=   typed_add   x  

Included Modules

Comparable

Constants

PRESENCE_STATUS = { :chat => 4, nil => 3, :dnd => 2, :away => 1, :xa => 0, :unavailable => -1, :error => -2 }   Compare two presences. The most suitable to talk with is the biggest.

Public Class methods

Create a new presence from a stanza

result:[Presence] Imported XMLStanza

[Source]

    # File lib/xmpp4r/presence.rb, line 42
42:     def Presence.import(xmlstanza)
43:       Presence::new.import(xmlstanza)
44:     end

Create presence stanza

show:[String] Initial Availability Status
status:[String] Initial status message
priority:[Fixnum] Initial priority value

[Source]

    # File lib/xmpp4r/presence.rb, line 20
20:     def initialize(show=nil, status=nil, priority=nil)
21:       super("presence")
22:       set_show(show) if show
23:       set_status(status) if status
24:       set_priority(priority) if priority
25:     end

Public Instance methods

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

[Source]

     # File lib/xmpp4r/presence.rb, line 224
224:     def <=>(o)
225:       if priority.to_i == o.priority.to_i
226:         cmp_interest(o)
227:       else
228:         priority.to_i <=> o.priority.to_i
229:       end
230:     end

[Source]

     # File lib/xmpp4r/presence.rb, line 242
242:     def cmp_interest(o)
243:       if type.nil?
244:         if o.type.nil?
245:           # both available.
246:           PRESENCE_STATUS[show] <=> PRESENCE_STATUS[o.show]
247:         else
248:           return -1
249:         end
250:       elsif o.type.nil?
251:         return 1
252:       else
253:         # both are non-nil. We consider this is equal.
254:         return 0
255:       end
256:     end

Get presence priority, or nil if absent

result:[Integer]

[Source]

     # File lib/xmpp4r/presence.rb, line 190
190:     def priority
191:        e = first_element_text('priority')
192:       if e
193:         return e.to_i
194:       else
195:         return nil
196:       end
197:     end

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

[Source]

     # File lib/xmpp4r/presence.rb, line 205
205:     def priority=(val)
206:       if val.nil?
207:         delete_element('priority')
208:       else
209:         replace_element_text('priority', val)
210:       end
211:     end

Set presence priority (chaining-friendly)

val:[Integer] Priority value between -128 and +127

[Source]

     # File lib/xmpp4r/presence.rb, line 216
216:     def set_priority(val)
217:       self.priority = val
218:       self
219:     end

Set Availability Status (chaining-friendly)

val:[Symbol] or [Nil] See show for explanation

[Source]

     # File lib/xmpp4r/presence.rb, line 156
156:     def set_show(val)
157:       self.show = val
158:       self
159:     end

Set status message (chaining-friendly)

val:[String] or nil

[Source]

     # File lib/xmpp4r/presence.rb, line 182
182:     def set_status(val)
183:       self.status = val
184:       self
185:     end

Set type of presence (chaining-friendly)

val:[Symbol] See type for possible subscription types

[Source]

    # File lib/xmpp4r/presence.rb, line 91
91:     def set_type(val)
92:       self.type = val
93:       self
94:     end

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)

[Source]

     # File lib/xmpp4r/presence.rb, line 117
117:     def show
118:       e = first_element('show')
119:       text = e ? e.text : nil
120:       case text
121:         when 'away' then :away
122:         when 'chat' then :chat
123:         when 'dnd' then :dnd
124:         when 'xa' then :xa
125:         else nil
126:       end
127:     end

Set Availability Status

val:[Symbol] or [Nil] See show for explanation

[Source]

     # File lib/xmpp4r/presence.rb, line 132
132:     def show=(val)
133:       xe = first_element('show')
134:       if xe.nil?
135:         xe = add_element('show')
136:       end
137:       case val
138:         when :away then text = 'away'
139:         when :chat then text = 'chat'
140:         when :dnd then text = 'dnd'
141:         when :xa then text = 'xa'
142:         when nil then text = nil
143:         else raise "Invalid value for show."
144:       end
145: 
146:       if text.nil?
147:         delete_element(xe)
148:       else
149:         xe.text = text
150:       end
151:     end

Get status message

result:[String] or nil

[Source]

     # File lib/xmpp4r/presence.rb, line 164
164:     def status
165:       first_element_text('status')
166:     end

Set status message

val:[String] or nil

[Source]

     # File lib/xmpp4r/presence.rb, line 171
171:     def status=(val)
172:       if val.nil?
173:         delete_element('status')
174:       else
175:         replace_element_text('status', val)
176:       end
177:     end

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.

[Source]

    # File lib/xmpp4r/presence.rb, line 59
59:     def type
60:       case super
61:         when 'error' then :error
62:         when 'probe' then :probe
63:         when 'subscribe' then :subscribe
64:         when 'subscribed' then :subscribed
65:         when 'unavailable' then :unavailable
66:         when 'unsubscribe' then :unsubscribe
67:         when 'unsubscribed' then :unsubscribed
68:         else nil
69:       end
70:     end

Set type of presence

val:[Symbol] See type for possible subscription types

[Source]

    # File lib/xmpp4r/presence.rb, line 75
75:     def type=(val)
76:       case val
77:         when :error then super('error')
78:         when :probe then super('probe')
79:         when :subscribe then super('subscribe')
80:         when :subscribed then super('subscribed')
81:         when :unavailable then super('unavailable')
82:         when :unsubscribe then super('unsubscribe')
83:         when :unsubscribed then super('unsubscribed')
84:         else super(nil)
85:       end
86:     end

Add an element to the presence stanza

  • <x/> elements are converted to [X]
element:[REXML::Element] to add

[Source]

    # File lib/xmpp4r/presence.rb, line 31
31:     def typed_add(element)
32:       if element.kind_of?(REXML::Element) && (element.name == 'x')
33:         super(X::import(element))
34:       else
35:         super(element)
36:       end
37:     end

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

[Source]

     # File lib/xmpp4r/presence.rb, line 100
100:     def x(namespace=nil)
101:       each_element('x') { |x|
102:         if namespace.nil? or namespace == x.namespace
103:           return x
104:         end
105:       }
106:       nil
107:     end

[Validate]