mad-p-xmpp4r 0.6.0

data/lib/xmpp4r/pubsub/iq/pubsub.rb

@@ -0,0 +1,19 @@
+# =XMPP4R - XMPP Library for Ruby
+# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
+# Website::http://home.gna.org/xmpp4r/
+
+require 'xmpp4r/iq'
+
+module Jabber
+  module PubSub
+    NS_PUBSUB = 'http://jabber.org/protocol/pubsub'
+    class IqPubSub < XMPPElement
+      name_xmlns 'pubsub', NS_PUBSUB
+      force_xmlns true
+    end
+    class IqPubSubOwner < XMPPElement
+      name_xmlns 'pubsub', NS_PUBSUB + '#owner'
+      force_xmlns true
+    end
+  end
+end

data/lib/xmpp4r/query.rb

@@ -0,0 +1,15 @@
+# =XMPP4R - XMPP Library for Ruby
+# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
+# Website::http://home.gna.org/xmpp4r/
+
+require 'xmpp4r/xmppelement'
+
+module Jabber
+  ##
+  # A class used to build/parse IQ Query requests/responses
+  #
+  class IqQuery < XMPPElement
+    name_xmlns 'query'
+    force_xmlns true
+  end
+end

data/lib/xmpp4r/reliable.rb

@@ -0,0 +1,168 @@
+require 'xmpp4r/stream'
+
+module Jabber
+  module Reliable
+    
+    class Connection < Jabber::Client
+      def initialize(full_jid, config)
+        super(full_jid)
+        @servers = config[:servers]
+        @port = config[:port] || 5222
+        @max_retry = config[:max_retry] || 30
+        @retry_sleep = config[:retry_sleep] || 2
+        if(@servers.nil? or @servers.empty?)
+          @servers = [@jid.domain]
+        end
+      end
+      
+      def connect
+        retry_count = 0
+        server_to_use = nil
+        server_pool = @servers.dup.sort{ rand <=> rand }
+        begin
+          server_to_use = server_pool.shift
+          server_pool.push(server_to_use)
+
+          Jabber::debuglog "timeout will be: #{@retry_sleep.to_f}"
+          Timeout.timeout(@retry_sleep.to_f){
+            Jabber::debuglog "trying to connect to #{server_to_use}"
+            super(server_to_use, @port)
+          }
+
+          Jabber::debuglog self.jid.to_s + " connected to " + server_to_use.to_s
+          Jabber::debuglog "out of possible servers " + @servers.inspect
+        rescue Exception, Timeout::Error => e
+          Jabber::warnlog "#{server_to_use} error: #{e.inspect}. Will attempt to reconnect in #{@retry_sleep}"
+          sleep(@retry_sleep.to_f)
+          if(retry_count >= @max_retry.to_i)
+            Jabber::warnlog "reached max retry count on exception, failing"
+            raise e
+          end
+          retry_count += 1
+          retry
+        end
+      end
+            
+    end
+    
+    class Listener
+      def initialize(full_jid, password, config, &block)
+        @on_message_block = block
+        @full_jid = full_jid
+        @config = config
+        @password = password
+        @max_retry = config[:max_retry] || 30
+      end
+      
+      def setup_connection
+        @connection = Connection.new(@full_jid, @config)
+        if @on_message_block
+          @connection.add_message_callback(&@on_message_block)
+        else
+          @connection.add_message_callback do |msg|
+            self.on_message(msg)
+          end
+        end
+        
+        #We could just reconnect in @connection.on_exception, 
+        #but by raising into this seperate thread, we avoid growing our stack trace
+        @reconnection_thread = Thread.new do
+          first_run = true
+          begin
+            self.start unless first_run
+            loop do 
+              sleep(1)
+              Thread.pass
+            end
+          rescue => e
+            first_run = false
+            retry
+          end
+        end
+        @exception_handlers = []
+        @connection.on_exception do |e, connection, where_failed|
+          self.run_exception_handlers(e, connection, where_failed)
+        end
+      end
+      
+      def run_exception_handlers(e, connection, where_failed)
+        @exception_handlers.each do |ex_handler|
+          ex_handler.call(e, connection, where_failed)
+        end
+        if where_failed == :sending
+          @message_to_send_on_reconnect = @message_now_sending
+        end
+        if where_failed != :close && !@connection.is_connected?
+          @reconnection_thread.raise(e)
+        end
+      end
+      
+      def add_exception_handler(&block)
+        @exception_handlers << block
+      end
+      
+      def start
+        setup_connection unless @connection
+        connect
+        auth
+        send_presence
+        if @message_to_send_on_reconnect
+          send_message(@message_to_send_on_reconnect)
+        end
+        @message_to_send_on_reconnect = nil
+      end
+      
+      #Stop the listener. (close the connection)
+      def stop
+        @connection.close if @connection and @connection.is_connected?
+        @connection = nil
+      end
+      
+      def connect
+        @connection.connect        
+      end
+      
+      def auth
+        @connection.auth(@password)
+      end
+      
+      def send_presence
+        presence_message = @config[:presence_message]
+        if presence_message && !presence_message.empty?
+          @connection.send(Jabber::Presence.new.set_show(:chat).set_status(presence_message))
+        end
+      end
+      
+      #TODO: test and fix situation where we get disconnected while sending but then successfully reconnect 
+      # (and make sure in such cases we resent)      
+      def send_message(message)
+        unless @connection
+          raise ::ArgumentError, "Can't send messages while listener is stopped.  Plase 'start' the listener first."
+        end
+        retry_count = 0
+        begin
+          while(not @connection.is_connected?)
+            #wait
+            Thread.pass
+          end
+          @message_now_sending = message
+          @connection.send(message)
+          return true #true, message was sent
+        rescue => e
+          if e.is_a?(Interrupt)
+            raise e
+          end
+          if(retry_count > @max_retry.to_i)
+            Jabber::debuglog "reached max retry count on message re-send, failing"
+            raise e
+          end
+          retry_count += 1
+          Jabber::debuglog "retrying message send.." + e.inspect
+          retry
+        end
+      end
+      
+    end
+    
+  end
+end

data/lib/xmpp4r/rexmladdons.rb

@@ -0,0 +1,197 @@
+# =XMPP4R - XMPP Library for Ruby
+# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
+# Website::http://home.gna.org/xmpp4r/
+
+require 'rexml/document'
+require 'rexml/parsers/xpathparser'
+require 'rexml/source'
+
+# Turn $VERBOSE off to suppress warnings about redefinition
+oldverbose = $VERBOSE
+$VERBOSE = false
+
+# REXML : Adds custom helper methods to the REXML module.
+#
+module REXML
+
+  # this class adds a few helper methods to REXML::Element
+  class Element
+
+    def each_elements(*els, &block)
+      els.inject([ ]) do |res, e|
+        res + each_element(e, &block)
+      end
+    end
+
+    ##
+    # Replaces or adds a child element of name <tt>e</tt> with text <tt>t</tt>.
+    def replace_element_text(e, t, namespace = nil)
+      el = first_element(e, namespace)
+      if el.nil?
+        el = REXML::Element.new(e)
+        el.add_namespace(namespace)
+        add_element(el)
+      end
+      if t
+        el.text = t
+      end
+      self
+    end
+    
+    ##
+    # Replaces or adds a child element of name <tt>e</tt> with content of <tt>t</tt>.
+    def replace_element_content(e, c, namespace = nil)
+      el = first_element(e, namespace)
+      if el.nil?
+        el = REXML::Element.new(e)
+        el.add_namespace(namespace)
+        add_element(el)
+      end
+      if c
+        el.children.each do |ch|
+          ch.remove
+        end
+        c.root.children.each do |ch|
+          el.add ch
+        end
+      end
+      self
+    end
+
+    ##
+    # Returns first element of name <tt>e</tt>
+    def first_element(e, namespace = nil)
+      if namespace
+        each_element_with_attribute("xmlns", namespace, 1, e) { |el| return el }
+      else
+        each_element(e) { |el| return el }
+      end
+      return nil
+    end
+
+    ##
+    # Returns text of first element of name <tt>e</tt>
+    def first_element_text(e, namespace = nil)
+      el = first_element(e, namespace)
+      if el
+        return el.text
+      else
+        return nil
+      end
+    end
+
+    ##
+    # This method works like <tt>first_element_text</tt> except that it
+    # returns content of all children, not just the value of the first
+    # child text element.
+    #
+    # Returns content of first element of name <tt>e</tt>
+    def first_element_content(e, namespace = nil)
+      el = first_element(e, namespace)
+      if el
+        return el.children.join
+      else
+        return nil
+      end
+    end
+
+    # This method does exactly the same thing as add(), but it can be
+    # overriden by subclasses to provide on-the-fly object creations.
+    # For example, if you import a REXML::Element of name 'plop', and you
+    # have a Plop class that subclasses REXML::Element, with typed_add you
+    # can get your REXML::Element to be "magically" converted to Plop.
+    def typed_add(e)
+      add(e)
+    end
+
+    ##
+    # import this element's children and attributes
+    def import(xmlelement)
+      if @name and @name != xmlelement.name
+        raise "Trying to import an #{xmlelement.name} to a #{@name} !"
+      end
+      add_attributes(xmlelement.attributes.clone)
+      @context = xmlelement.context
+      xmlelement.each do |e|
+        if e.kind_of? REXML::Element
+          typed_add(e.deep_clone)
+        elsif e.kind_of? REXML::Text
+          add_text(e.value)
+        else
+          add(e.clone)
+        end
+      end
+      self
+    end
+
+    def self.import(xmlelement)
+      self.new(xmlelement.name).import(xmlelement)
+    end
+
+    ##
+    # Deletes one or more children elements,
+    # not just one like REXML::Element#delete_element
+    def delete_elements(element)
+      while(delete_element(element)) do end
+    end
+
+    ##
+    # Test for equality of two elements, useful for assert_equal in
+    # test cases. Tries to parse String o as XML.
+    #
+    # See Test::Unit::Assertions
+    def ==(o)
+      return false unless self.kind_of? REXML::Element
+      if o.kind_of? REXML::Element
+        # Ok
+      elsif o.kind_of? String
+        # Parse o
+        begin
+          o = REXML::Document.new(o).root
+        rescue REXML::ParseException
+          return false
+        end
+      else
+        # Cannot compare with anything other than Elements or Strings
+        return false
+      end
+
+      return false unless name == o.name
+
+      attributes.each_attribute do |attr|
+        return false unless attr.value == o.attributes[attr.name]
+      end
+
+      o.attributes.each_attribute do |attr|
+        return false unless attributes[attr.name] == attr.value
+      end
+
+      children.each_with_index do |child,i|
+        return false unless child == o.children[i]
+      end
+
+      return true
+    end
+
+  end # class Element
+
+  # FIXME : Is this still needed now that we're a bit past Ruby 1.8.3??
+  # Very dirty fix for the :progress problem in REXML from Ruby 1.8.3
+  # http://www.germane-software.com/projects/rexml/ticket/34
+  # the fix proposed in REXML changeset 1145 only fixes this for pipes, not for
+  # TCP sockets, so we have to keep this.
+  class IOSource
+    def position
+      0
+    end
+
+    def current_line
+      [0, 0, ""]
+    end
+  end # class IOSource
+
+end # module REXML
+
+# Restore the old $VERBOSE setting
+$VERBOSE = oldverbose
+

data/lib/xmpp4r/roster.rb

@@ -0,0 +1,7 @@
+# =XMPP4R - XMPP Library for Ruby
+# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
+# Website::http://home.gna.org/xmpp4r/
+
+require 'xmpp4r/roster/iq/roster.rb'
+require 'xmpp4r/roster/helper/roster.rb'
+require 'xmpp4r/roster/x/roster.rb'

data/lib/xmpp4r/roster/helper/roster.rb

@@ -0,0 +1,532 @@
+# =XMPP4R - XMPP Library for Ruby
+# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
+# Website::http://home.gna.org/xmpp4r/
+
+require 'xmpp4r/callbacks'
+require 'thread'
+require 'xmpp4r/roster/iq/roster'
+
+module Jabber
+  module Roster
+    ##
+    # The Roster helper intercepts <tt><iq/></tt> stanzas with Jabber::IqQueryRoster
+    # and <tt><presence/></tt> stanzas, but provides cbs which allow the programmer
+    # to keep track of updates.
+    #
+    # A thread for any received stanza is spawned, so the user can invoke
+    # accept_subscription et al in the callback blocks, without stopping
+    # the current (= parser) thread when waiting for a reply.
+    class Helper
+      ##
+      # All items in your roster
+      # items:: [Hash] ([JID] => [Roster::Helper::RosterItem])
+      attr_reader :items
+
+      ##
+      # Initialize a new Roster helper
+      #
+      # Registers its cbs (prio = 120, ref = self)
+      #
+      # Request a roster
+      # (Remember to send initial presence afterwards!)
+      #
+      # The initialization will not wait for the roster being received,
+      # use wait_for_roster.
+      #
+      # <b>Attention:</b> If you send presence and receive presences
+      # before the roster has arrived, the Roster helper will let them
+      # pass through and does *not* keep them!
+      def initialize(stream, startnow = true)
+        @stream = stream
+        @items = {}
+        @items_lock = Mutex.new
+        @roster_wait = Semaphore.new
+        @query_cbs = CallbackList.new
+        @update_cbs = CallbackList.new
+        @presence_cbs = CallbackList.new
+        @subscription_cbs = CallbackList.new
+        @subscription_request_cbs = CallbackList.new
+
+        # Register cbs
+        stream.add_iq_callback(120, self) { |iq|
+          if iq.query.kind_of?(IqQueryRoster)
+            Thread.new do
+              Thread.current.abort_on_exception = true
+              handle_iq_query_roster(iq)
+            end
+
+            true
+          else
+            false
+          end
+        }
+        stream.add_presence_callback(120, self) { |pres|
+          Thread.new do
+            Thread.current.abort_on_exception = true
+            handle_presence(pres)
+          end
+        }
+        get_roster if startnow
+      end
+
+      def get_roster
+        # Request the roster
+        rosterget = Iq.new_rosterget
+        @stream.send(rosterget)
+      end
+
+      ##
+      # Wait for first roster query result to arrive
+      def wait_for_roster
+        @roster_wait.wait
+        @roster_wait.run
+      end
+
+      ##
+      # Add a callback to be called when a query has been processed
+      #
+      # Because update callbacks are called for each roster item,
+      # this may be appropriate to notify that *anything* has updated.
+      #
+      # Arguments for callback block: The received <tt><iq/></tt> stanza
+      def add_query_callback(prio = 0, ref = nil, &block)
+        @query_cbs.add(prio, ref, block)
+      end
+
+      ##
+      # Add a callback for Jabber::Roster::Helper::RosterItem updates
+      #
+      # Note that this will be called much after initialization
+      # for the answer of the initial roster request
+      #
+      # The block receives two objects:
+      # * the old Jabber::Roster::Helper::RosterItem
+      # * the new Jabber::Roster::Helper::RosterItem
+      def add_update_callback(prio = 0, ref = nil, &block)
+        @update_cbs.add(prio, ref, block)
+      end
+
+      ##
+      # Add a callback for Jabber::Presence updates
+      #
+      # This will be called for <tt><presence/></tt> stanzas for known RosterItems.
+      # Unknown JIDs may still pass and can be caught via Jabber::Stream#add_presence_callback.
+      #
+      # The block receives three objects:
+      # * the Jabber::Roster::Helper::RosterItem
+      # * the old Jabber::Presence (or nil)
+      # * the new Jabber::Presence (or nil)
+      def add_presence_callback(prio = 0, ref = nil, &block)
+        @presence_cbs.add(prio, ref, block)
+      end
+
+      ##
+      # Add a callback for subscription updates,
+      # which will be called upon receiving a <tt><presence/></tt> stanza
+      # with type:
+      # * :subscribed
+      # * :unsubscribe
+      # * :unsubscribed
+      #
+      # The block receives two objects:
+      # * the Jabber::Roster::Helper::RosterItem (or nil)
+      # * the <tt><presence/></tt> stanza
+      def add_subscription_callback(prio = 0, ref = nil, &block)
+        @subscription_cbs.add(prio, ref, block)
+      end
+
+      ##
+      # Add a callback for subscription requests,
+      # which will be called upon receiving a <tt><presence type='subscribe'/></tt> stanza
+      #
+      # The block receives two objects:
+      # * the Jabber::Roster::Helper::RosterItem (or nil)
+      # * the <tt><presence/></tt> stanza
+      #
+      # Response to this event can be taken with accept_subscription
+      # and decline_subscription.
+      #
+      # Example usage:
+      #  my_roster.add_subscription_request_callback do |item,presence|
+      #    if accept_subscription_requests
+      #      my_roster.accept_subscription(presence.from)
+      #    else
+      #      my_roster.decline_subscription(presence.from)
+      #    end
+      #  end
+      def add_subscription_request_callback(prio = 0, ref = nil, &block)
+        @subscription_request_cbs.add(prio, ref, block)
+      end
+
+      private
+
+      ##
+      # Handle received <tt><iq/></tt> stanzas,
+      # used internally
+      def handle_iq_query_roster(iq)
+        # If the <iq/> contains <error/> we just ignore that
+        # and assume an empty roster
+        iq.query.each_element('item') do |item|
+          olditem, newitem = nil, nil
+
+          @items_lock.synchronize {
+            olditem = @items[item.jid]
+
+            # Handle deletion of item
+            if item.subscription == :remove
+              @items.delete(item.jid)
+            else
+              newitem = @items[item.jid] = RosterItem.new(@stream).import(item)
+            end
+          }
+          @update_cbs.process(olditem, newitem)
+        end
+
+        @roster_wait.run
+        @query_cbs.process(iq)
+      end
+
+      ##
+      # Handle received <tt><presence/></tt> stanzas,
+      # used internally
+      def handle_presence(pres)
+        item = self[pres.from]
+
+        if [:subscribed, :unsubscribe, :unsubscribed].include?(pres.type)
+          @subscription_cbs.process(item, pres)
+          true
+
+        elsif pres.type == :subscribe
+          @subscription_request_cbs.process(item, pres)
+          true
+
+        else
+          unless item.nil?
+            update_presence(item, pres)
+            true  # Callback consumed stanza
+          else
+            false # Callback did not consume stanza
+          end
+        end
+      end
+
+      ##
+      # Update the presence of an item,
+      # used internally
+      #
+      # Callbacks are called here
+      def update_presence(item, pres)
+
+        # This requires special handling, to announce all resources offline
+        if pres.from.resource.nil? and pres.type == :error
+          oldpresences = []
+          item.each_presence do |oldpres|
+            oldpresences << oldpres
+          end
+
+          item.add_presence(pres)
+          oldpresences.each { |oldpres|
+            @presence_cbs.process(item, oldpres, pres)
+          }
+        else
+          oldpres = item.presence_of(pres.from).nil? ?
+            nil :
+            Presence.new.import(item.presence_of(pres.from))
+
+          item.add_presence(pres)
+          @presence_cbs.process(item, oldpres, pres)
+        end
+      end
+
+      public
+
+      ##
+      # Get an item by jid
+      #
+      # If not available tries to look for it with the resource stripped
+      def [](jid)
+        jid = JID.new(jid) unless jid.kind_of? JID
+
+        @items_lock.synchronize {
+          if @items.has_key?(jid)
+            @items[jid]
+          elsif @items.has_key?(jid.strip)
+            @items[jid.strip]
+          else
+            nil
+          end
+        }
+      end
+
+      ##
+      # Returns the list of RosterItems which, stripped, are equal to the
+      # one you are looking for.
+      def find(jid)
+        jid = JID.new(jid) unless jid.kind_of? JID
+
+        j = jid.strip
+        l = {}
+        @items_lock.synchronize {
+          @items.each_pair do |k, v|
+            l[k] = v if k.strip == j
+          end
+        }
+        l
+      end
+
+      ##
+      # Groups in this Roster,
+      # sorted by name
+      #
+      # Contains +nil+ if there are ungrouped items
+      # result:: [Array] containing group names (String)
+      def groups
+        res = []
+        @items_lock.synchronize {
+          @items.each_pair do |jid,item|
+            res += item.groups
+            res += [nil] if item.groups == []
+          end
+        }
+        res.uniq.sort { |a,b| a.to_s <=> b.to_s }
+      end
+
+      ##
+      # Get items in a group
+      #
+      # When group is nil, return ungrouped items
+      # group:: [String] Group name
+      # result:: Array of [RosterItem]
+      def find_by_group(group)
+        res = []
+        @items_lock.synchronize {
+          @items.each_pair do |jid,item|
+            res.push(item) if item.groups.include?(group)
+            res.push(item) if item.groups == [] and group.nil?
+          end
+        }
+        res
+      end
+
+      ##
+      # Add a user to your roster
+      #
+      # Threading is encouraged as the function waits for
+      # a result. ServerError is thrown upon error.
+      #
+      # See Jabber::Roster::Helper::RosterItem#subscribe for details
+      # about subscribing. (This method isn't used here but the
+      # same functionality applies.)
+      #
+      # If the item is already in the local roster
+      # it will simply send itself
+      # jid:: [JID] to add
+      # iname:: [String] Optional item name
+      # subscribe:: [Boolean] Whether to subscribe to this jid
+      def add(jid, iname=nil, subscribe=false)
+        if self[jid]
+          self[jid].send
+        else
+          request = Iq.new_rosterset
+          request.query.add(Jabber::Roster::RosterItem.new(jid, iname))
+          @stream.send_with_id(request)
+          # Adding to list is handled by handle_iq_query_roster
+        end
+
+        if subscribe
+          # Actually the item *should* already be known now,
+          # but we do it manually to exclude conditions.
+          pres = Presence.new.set_type(:subscribe).set_to(jid.strip)
+          @stream.send(pres)
+        end
+      end
+
+      ##
+      # Accept a subscription request
+      # * Sends a <presence type='subscribed'/> stanza
+      # * Adds the contact to your roster
+      # jid:: [JID] of contact
+      # iname:: [String] Optional roster item name
+      def accept_subscription(jid, iname=nil)
+        pres = Presence.new.set_type(:subscribed).set_to(jid.strip)
+        @stream.send(pres)
+
+        unless self[jid.strip]
+          request = Iq.new_rosterset
+          request.query.add(Jabber::Roster::RosterItem.new(jid.strip, iname))
+          @stream.send_with_id(request)
+        end
+      end
+
+      ##
+      # Decline a subscription request
+      # * Sends a <presence type='unsubscribed'/> stanza
+      def decline_subscription(jid)
+        pres = Presence.new.set_type(:unsubscribed).set_to(jid.strip)
+        @stream.send(pres)
+      end
+
+      ##
+      # These are extensions to RosterItem to carry presence information.
+      # This information is *not* stored in XML!
+      class RosterItem < Jabber::Roster::RosterItem
+        ##
+        # Tracked (online) presences of this RosterItem
+        attr_reader :presences
+
+        ##
+        # Initialize an empty RosterItem
+        def initialize(stream)
+          super()
+          @stream = stream
+          @presences = []
+          @presences_lock = Mutex.new
+        end
+
+        ##
+        # Send the updated RosterItem to the server,
+        # i.e. if you modified iname, groups, ...
+        def send
+          request = Iq.new_rosterset
+          request.query.add(self)
+          @stream.send(request)
+        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 ServerError upon failure.
+        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
+
+        ##
+        # Is any presence of this person on-line?
+        #
+        # (Or is there any presence? Unavailable presences are
+        # deleted.)
+        def online?
+          @presences_lock.synchronize {
+            @presences.select { |pres|
+              pres.type.nil?
+            }.size > 0
+          }
+        end
+
+        ##
+        # Iterate through all received <tt><presence/></tt> stanzas
+        def each_presence(&block)
+          # Don't lock here, we don't know what block does...
+          @presences.each { |pres|
+            yield(pres)
+          }
+        end
+
+        ##
+        # Get specific presence
+        # jid:: [JID] Full JID with resource
+        def presence_of(jid)
+          @presences_lock.synchronize {
+            @presences.each { |pres|
+              return(pres) if pres.from == jid
+            }
+          }
+          nil
+        end
+
+        ##
+        # Get presence of highest-priority available resource of this person
+        #
+        # Returns <tt>nil</tt> if contact is offline
+        def presence
+          @presences_lock.synchronize {
+            @presences.select { |pres|
+              pres.type.nil?
+            }.max { |pres1, pres2| (pres1.priority || 0) <=> (pres2.priority || 0) }
+          }
+        end
+
+        ##
+        # 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. Old presence stanzas with
+        # <tt>type == :unavailable</tt> will be deleted.
+        #
+        # If <tt>type == :error</tt> and the presence's origin has no
+        # specific resource the contact is treated completely offline.
+        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? or pres.type == :unavailable
+            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
+
+        ##
+        # 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. ;-)
+        def subscribe
+          pres = Presence.new.set_type(:subscribe).set_to(jid.strip)
+          @stream.send(pres)
+        end
+
+        ##
+        # 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.
+        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
+
+        ##
+        # 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'.
+        def cancel_subscription
+          pres = Presence.new.set_type(:unsubscribed).set_to(jid)
+          @stream.send(pres)
+        end
+      end
+    end #Class Roster
+  end #Module Roster
+end #Module Jabber