Class Jabber::Roster::Helper::RosterItem
In: lib/xmpp4r/roster/helper/roster.rb
Parent: Jabber::Roster::RosterItem

These are extensions to RosterItem to carry presence information. This information is not stored in XML!

Methods

Attributes

presences  [R]  Tracked (online) presences of this RosterItem

Public Class methods

Initialize an empty RosterItem

[Source]

     # File lib/xmpp4r/roster/helper/roster.rb, line 356
356:         def initialize(stream)
357:           super()
358:           @stream = stream
359:           @presences = []
360:           @presences_lock = Mutex.new
361:         end

Public Instance methods

Add presence and sort presences (unless type is :unavailable or :error)

This overwrites previous stanzas with the same destination JID to keep track of resources. Presence stanzas with type == :unavailable or type == :error will be deleted as this indicates that this resource has gone offline.

If type == :error and the presence‘s origin has no specific resource the contact is treated completely offline.

[Source]

     # File lib/xmpp4r/roster/helper/roster.rb, line 447
447:         def add_presence(newpres)
448:           @presences_lock.synchronize {
449:             # Delete old presences with the same JID
450:             @presences.delete_if do |pres|
451:               pres.from == newpres.from or pres.from.resource.nil?
452:             end
453: 
454:             if newpres.type == :error and newpres.from.resource.nil?
455:               # Replace by single error presence
456:               @presences = [newpres]
457:             else
458:               # Add new presence
459:               @presences.push(newpres)
460:             end
461: 
462:             @presences.sort!
463:           }
464:         end

Deny the contact to see your presence.

This method will not wait and returns immediately as you will need no confirmation for this action.

Though, you will get a roster update for that item, carrying either subscription=‘to’ or ‘none’.

[Source]

     # File lib/xmpp4r/roster/helper/roster.rb, line 506
506:         def cancel_subscription
507:           pres = Presence.new.set_type(:unsubscribed).set_to(jid)
508:           @stream.send(pres)
509:         end

Iterate through all received <presence/> stanzas

[Source]

     # File lib/xmpp4r/roster/helper/roster.rb, line 416
416:         def each_presence(&block)
417:           # Don't lock here, we don't know what block does...
418:           @presences.each { |pres|
419:             yield(pres)
420:           }
421:         end

Import another element, also import presences if xe is a RosterItem

return:[RosterItem] self

[Source]

     # File lib/xmpp4r/roster/helper/roster.rb, line 367
367:         def import(xe)
368:           super
369:           if xe.kind_of?(RosterItem)
370:             xe.each_presence { |pres|
371:               add_presence(Presence.new.import(pres))
372:             }
373:           end
374:           self
375:         end

Is any presence of this person on-line?

(Or is there any presence? Unavailable presences are deleted.)

[Source]

     # File lib/xmpp4r/roster/helper/roster.rb, line 406
406:         def online?
407:           @presences_lock.synchronize {
408:             @presences.select { |pres|
409:               pres.type.nil?
410:             }.size > 0
411:           }
412:         end

Get specific presence

jid:[JID] Full JID

[Source]

     # File lib/xmpp4r/roster/helper/roster.rb, line 426
426:         def presence(jid)
427:           @presences_lock.synchronize {
428:             @presences.each { |pres|
429:               return(pres) if pres.from == jid
430:             }
431:           }
432:           nil
433:         end

Remove item

This cancels both subscription from the contact to you and from you to the contact.

The methods waits for a roster push from the server (success) or throws ErrorException upon failure.

[Source]

     # File lib/xmpp4r/roster/helper/roster.rb, line 394
394:         def remove
395:           request = Iq.new_rosterset
396:           request.query.add(Jabber::Roster::RosterItem.new(jid, nil, :remove))
397:           @stream.send_with_id(request) { true }
398:           # Removing from list is handled by Roster#handle_iq
399:         end

Send the updated RosterItem to the server, i.e. if you modified iname, groups, …

[Source]

     # File lib/xmpp4r/roster/helper/roster.rb, line 380
380:         def send
381:           request = Iq.new_rosterset
382:           request.query.add(self)
383:           @stream.send(request)
384:         end

Send subscription request to the user

The block given to Jabber::Roster::Roster#add_update_callback will be called, carrying the RosterItem with ask="subscribe"

This function returns immediately after sending the subscription request and will not wait of approval or declination as it may take months for the contact to decide. ;-)

[Source]

     # File lib/xmpp4r/roster/helper/roster.rb, line 475
475:         def subscribe
476:           pres = Presence.new.set_type(:subscribe).set_to(jid.strip)
477:           @stream.send(pres)
478:         end

Unsubscribe from a contact‘s presence

This method waits for a presence with type=‘unsubscribed’ from the contact. It may throw ErrorException upon failure.

subscription attribute of the item is from or none afterwards. As long as you don‘t remove that item and subscription=‘from’ the contact is subscribed to your presence.

[Source]

     # File lib/xmpp4r/roster/helper/roster.rb, line 490
490:         def unsubscribe
491:           pres = Presence.new.set_type(:unsubscribe).set_to(jid.strip)
492:           @stream.send(pres) { |answer|
493:             answer.type == :unsubscribed and
494:             answer.from.strip == pres.to
495:           }
496:         end

[Validate]