Class: Jabber::Roster::Helper::RosterItem

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

add_presence cancel_subscription each_presence new online? presence remove send subscribe unsubscribe

### Attributes

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

### Public Class methods

new(stream)

Initialize an empty RosterItem

[Source]

         # File lib/xmpp4r/roster/helper/roster.rb, line 376
    376:         def initialize(stream)
    377:           super()
    378:           @stream = stream
    379:           @presences = []
    380:           @presences_lock = Mutex.new
    381:         end

### Public Instance methods

add_presence(newpres)

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 453
    453:         def add_presence(newpres)
    454:           @presences_lock.synchronize {
    455:             # Delete old presences with the same JID
    456:             @presences.delete_if do |pres|
    457:               pres.from == newpres.from or pres.from.resource.nil?
    458:             end
    459:
    460:             if newpres.type == :error and newpres.from.resource.nil?
    461:               # Replace by single error presence
    462:               @presences = [newpres]
    463:             else
    464:               # Add new presence
    465:               @presences.push(newpres)
    466:             end
    467:
    468:             @presences.sort!
    469:           }
    470:         end

cancel_subscription()

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 512
    512:         def cancel_subscription
    513:           pres = Presence.new.set_type(:unsubscribed).set_to(jid)
    514:           @stream.send(pres)
    515:         end

each_presence() {|pres| ...}

Iterate through all received `<presence/>` stanzas

[Source]

         # File lib/xmpp4r/roster/helper/roster.rb, line 422
    422:         def each_presence(&block)
    423:           # Don't lock here, we don't know what block does...
    424:           @presences.each { |pres|
    425:             yield(pres)
    426:           }
    427:         end

online?()

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 412
    412:         def online?
    413:           @presences_lock.synchronize {
    414:             @presences.select { |pres|
    415:               pres.type.nil?
    416:             }.size > 0
    417:           }
    418:         end

presence(jid)

Get specific presence

jid: | [JID] Full JID

[Source]

         # File lib/xmpp4r/roster/helper/roster.rb, line 432
    432:         def presence(jid)
    433:           @presences_lock.synchronize {
    434:             @presences.each { |pres|
    435:               return(pres) if pres.from == jid
    436:             }
    437:           }
    438:           nil
    439:         end

remove()

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 ServerError upon failure.

[Source]

         # File lib/xmpp4r/roster/helper/roster.rb, line 400
    400:         def remove
    401:           request = Iq.new_rosterset
    402:           request.query.add(Jabber::Roster::RosterItem.new(jid, nil, :remove))
    403:           @stream.send_with_id(request)
    404:           # Removing from list is handled by Roster#handle_iq_query_roster
    405:         end

send()

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

[Source]

         # File lib/xmpp4r/roster/helper/roster.rb, line 386
    386:         def send
    387:           request = Iq.new_rosterset
    388:           request.query.add(self)
    389:           @stream.send(request)
    390:         end

subscribe()

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 481
    481:         def subscribe
    482:           pres = Presence.new.set_type(:subscribe).set_to(jid.strip)
    483:           @stream.send(pres)
    484:         end

unsubscribe()

Unsubscribe from a contact‘s presence

This method waits for a presence with type=‘unsubscribed’ from the contact. It may throw ServerError 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 496
    496:         def unsubscribe
    497:           pres = Presence.new.set_type(:unsubscribe).set_to(jid.strip)
    498:           @stream.send(pres) { |answer|
    499:             answer.type == :unsubscribed and
    500:             answer.from.strip == pres.to
    501:           }
    502:         end

[Validate]