class Jabber::Roster::Helper::RosterItem

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

Attributes

presences[R]

Tracked (online) presences of this RosterItem

Public Class Methods

new(stream) click to toggle source

Initialize an empty RosterItem

Calls superclass method Jabber::Roster::RosterItem.new
# File lib/xmpp4r/roster/helper/roster.rb, line 379
def initialize(stream)
  super()
  @stream = stream
  @presences = []
  @presences_lock = Mutex.new
end

Public Instance Methods

add_presence(newpres) click to toggle source

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.

# File lib/xmpp4r/roster/helper/roster.rb, line 456
def add_presence(newpres)
  @presences_lock.synchronize {
    # Delete old presences with the same JID
    @presences.delete_if do |pres|
      pres.from == newpres.from or pres.from.resource.nil?
    end

    if newpres.type == :error and newpres.from.resource.nil?
      # Replace by single error presence
      @presences = [newpres]
    else
      # Add new presence
      @presences.push(newpres)
    end

    @presences.sort!
  }
end
cancel_subscription() click to toggle source

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

# File lib/xmpp4r/roster/helper/roster.rb, line 515
def cancel_subscription
  pres = Presence.new.set_type(:unsubscribed).set_to(jid)
  @stream.send(pres)
end
each_presence() { |pres| ... } click to toggle source

Iterate through all received <presence/> stanzas

# File lib/xmpp4r/roster/helper/roster.rb, line 425
def each_presence(&block)
  # Don't lock here, we don't know what block does...
  @presences.each { |pres|
    yield(pres)
  }
end
online?() click to toggle source

Is any presence of this person on-line?

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

# File lib/xmpp4r/roster/helper/roster.rb, line 415
def online?
  @presences_lock.synchronize {
    @presences.select { |pres|
      pres.type.nil?
    }.size > 0
  }
end
presence(jid) click to toggle source

Get specific presence

jid
JID

Full JID

# File lib/xmpp4r/roster/helper/roster.rb, line 435
def presence(jid)
  @presences_lock.synchronize {
    @presences.each { |pres|
      return(pres) if pres.from == jid
    }
  }
  nil
end
remove() click to toggle source

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.

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

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

# File lib/xmpp4r/roster/helper/roster.rb, line 389
def send
  request = Iq.new_rosterset
  request.query.add(self)
  @stream.send(request)
end
subscribe() click to toggle source

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

# File lib/xmpp4r/roster/helper/roster.rb, line 484
def subscribe
  pres = Presence.new.set_type(:subscribe).set_to(jid.strip)
  @stream.send(pres)
end
unsubscribe() click to toggle source

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.

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