Class Jabber::Presence
In: lib/xmpp4r/presence.rb
Parent: XMLStanza
X XDelay XMuc XRoster XMucUser REXML::Element XRosterItem IqQuery XMLStanza IqVcard DiscoIdentity XMucUserItem DiscoItem Error RosterItem DiscoFeature IqQueryRoster IqQueryVersion IqQueryDiscoItems IqQueryDiscoInfo Message Presence Iq Singleton IdGenerator Connection Client Component Comparable JID RuntimeError ErrorException AuthenticationFailure RosterItem Stream StreamParser Roster Vcard Version lib/xmpp4r/authenticationfailure.rb lib/xmpp4r/iq/query/roster.rb lib/xmpp4r/idgenerator.rb lib/xmpp4r/iq/query/version.rb lib/xmpp4r/connection.rb lib/xmpp4r/x/mucuseritem.rb lib/xmpp4r/x/roster.rb lib/xmpp4r/iq.rb lib/xmpp4r/jid.rb lib/xmpp4r/iq/query.rb lib/xmpp4r/xmlstanza.rb lib/xmpp4r/x/delay.rb lib/xmpp4r/errorexception.rb lib/xmpp4r/client.rb lib/xmpp4r/stream.rb lib/xmpp4r/x/muc.rb lib/xmpp4r/streamparser.rb lib/xmpp4r/x.rb lib/xmpp4r/iq/vcard.rb lib/xmpp4r/iq/query/discoinfo.rb lib/xmpp4r/error.rb lib/xmpp4r/component.rb lib/xmpp4r/message.rb lib/xmpp4r/iq/query/discoitems.rb lib/xmpp4r/presence.rb lib/xmpp4r/helpers/roster.rb lib/xmpp4r/helpers/vcard.rb lib/xmpp4r/helpers/version.rb Helpers Jabber Module: Jabber

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

[Source]

     # File lib/xmpp4r/presence.rb, line 219
219:     def <=>(o)
220:       if priority.nil?
221:         if o.priority.nil?
222:           return 0
223:         else
224:           return 1
225:         end
226:       elsif o.priority.nil?
227:         return -1
228:       else
229:         return priority <=> o.priority
230:       end
231:     end

[Source]

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

Get presence priority, or nil if absent

result:[Integer]

[Source]

     # File lib/xmpp4r/presence.rb, line 186
186:     def priority
187:       e = first_element_text('priority')
188:       if e
189:         return e.to_i
190:       else
191:         return nil
192:       end
193:     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 201
201:     def priority=(val)
202:       if val.nil?
203:         delete_element('priority')
204:       else
205:         replace_element_text('priority', val)
206:       end
207:     end

Set presence priority (chaining-friendly)

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

[Source]

     # File lib/xmpp4r/presence.rb, line 212
212:     def set_priority(val)
213:       self.priority = val
214:       self
215:     end

Set Availability Status (chaining-friendly)

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

[Source]

     # File lib/xmpp4r/presence.rb, line 152
152:     def set_show(val)
153:       self.show = val
154:       self
155:     end

Set status message (chaining-friendly)

val:[String] or nil

[Source]

     # File lib/xmpp4r/presence.rb, line 178
178:     def set_status(val)
179:       self.status = val
180:       self
181:     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 113
113:     def show
114:       e = first_element('show')
115:       text = e ? e.text : nil
116:       case text
117:         when 'away' then :away
118:         when 'chat' then :chat
119:         when 'dnd' then :dnd
120:         when 'xa' then :xa
121:         else nil
122:       end
123:     end

Set Availability Status

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

[Source]

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

Get status message

result:[String] or nil

[Source]

     # File lib/xmpp4r/presence.rb, line 160
160:     def status
161:       first_element_text('status')
162:     end

Set status message

val:[String] or nil

[Source]

     # File lib/xmpp4r/presence.rb, line 167
167:     def status=(val)
168:       if val.nil?
169:         delete_element('status')
170:       else
171:         replace_element_text('status', val)
172:       end
173:     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 of this stanza

result:[REXML::Element] or nil

[Source]

     # File lib/xmpp4r/presence.rb, line 99
 99:     def x
100:       xe = nil
101:       each_element('x') { |e| xe = e }
102:       xe
103:     end

[Validate]