gmcmillan-xmpp4r 0.5

data/lib/xmpp4r/discovery.rb

@@ -0,0 +1,8 @@
+# =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/discovery/iq/discoinfo'
+require 'xmpp4r/discovery/iq/discoitems'
+require 'xmpp4r/discovery/helper/helper'
+require 'xmpp4r/discovery/helper/responder'

data/lib/xmpp4r/discovery/helper/helper.rb

@@ -0,0 +1,58 @@
+# =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'
+require 'xmpp4r/discovery'
+
+module Jabber
+  module Discovery
+    ##
+    # A Helper to manage service and item discovery.
+    class Helper
+      def initialize(client)
+        @stream = client
+      end
+
+      ##
+      # Service discovery on a JID.
+      # jid:: [JID]
+      # return:: [Jabber::Discovery::IqQueryDiscoInfo]
+      def get_info_for(jid, node = nil)
+        iq = Jabber::Iq.new(:get, jid)
+        iq.from = @stream.jid
+        disco = Jabber::Discovery::IqQueryDiscoInfo.new
+        disco.node = node
+        iq.add(disco)
+
+        res = nil
+
+        @stream.send_with_id(iq) { |reply|
+          res = reply.query
+        }
+
+        res
+      end
+
+      ##
+      # Item discovery on a JID.
+      # jid:: [JID]
+      # return:: [Jabber::Discovery::IqQueryDiscoItems]
+      def get_items_for(jid, node = nil)
+        iq = Jabber::Iq.new(:get, jid)
+        iq.from = @stream.jid
+        disco = Jabber::Discovery::IqQueryDiscoItems.new
+        disco.node = node
+        iq.add(disco)
+
+        res = nil
+
+        @stream.send_with_id(iq) { |reply|
+          res = reply.query
+        }
+
+        res
+      end
+    end
+  end
+end

data/lib/xmpp4r/discovery/helper/responder.rb

@@ -0,0 +1,165 @@
+# =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'
+require 'xmpp4r/discovery/iq/discoinfo'
+require 'xmpp4r/discovery/iq/discoitems'
+require 'xmpp4r/caps/helper/generator'
+
+module Jabber
+  module Discovery
+    ##
+    # Responds to Service Discovery queries on a given node
+    #
+    # Modify returned elements by these attributes:
+    # * Responder#identities
+    # * Responder#features (Responder#add_features is a short-cut accepting an Array of Strings, too)
+    # * Responder#forms
+    # * Responder#items
+    class Responder
+      ##
+      # Service Discovery node this Responder is responsible for
+      # (will not answer queries for other nodes)
+      attr_reader :node
+
+      ##
+      # Identities returned on Discovery Info query
+      #
+      # Array of [Discovery::Identity]
+      attr_accessor :identities
+      ##
+      # Features returned on Discovery Info query,
+      #
+      # Array of [Discovery::Feature]
+      attr_accessor :features
+      ##
+      # Forms returned on Discovery Info query
+      # (such as Software Information)
+      #
+      # Array of [Dataforms::XData]
+      attr_accessor :forms
+
+      ##
+      # Children returned on Discovery Item query
+      #
+      # May contain other Discovery::Responder instances
+      # which will generate an item dynamically from their
+      # first identity
+      #
+      # Array of [Discovery::Item] or [Discovery::Responder] (mixed)
+      attr_accessor :items
+
+      ##
+      # Set the JID this helper feels responsible for
+      # (default: nil, responsible for any JID)
+      attr_accessor :my_jid
+
+      CALLBACK_PRIORITY = 180
+
+      ##
+      # Initialize responder for a specific node
+      # stream:: [Jabber::Stream]
+      # node:: [nil] or [String]
+      def initialize(stream, node=nil, identities=[], features=[], items=[])
+        @stream = stream
+        @my_jid = nil
+        @node = node
+        @identities = identities
+        @features = []
+        add_features(features)
+        @forms = []
+        @items = items
+
+        @stream.add_iq_callback(CALLBACK_PRIORITY, self) do |iq|
+          my_nodes = [@node, "#{@node}##{generate_ver}"]
+
+          if iq.type == :get and
+             iq.query.kind_of? IqQueryDiscoInfo and
+             my_nodes.include?(iq.query.node)
+
+            answer = iq.answer(false)
+            answer.type = :result
+            query = answer.add(IqQueryDiscoInfo.new)
+            query.node = iq.query.node
+            (@identities + @features + @forms).each do |element|
+              query.add(element)
+            end
+            @stream.send(answer)
+
+            true  # handled
+
+          elsif iq.type == :get and
+                iq.query.kind_of? IqQueryDiscoItems and
+                my_nodes.include?(iq.query.node)
+
+            answer = iq.answer(false)
+            answer.type = :result
+            query = answer.add(IqQueryDiscoItems.new)
+            query.node = iq.query.node
+            @items.each do |item|
+              if item.kind_of? Responder
+                query.add(item.generate_item)
+              else
+                query.add(item)
+              end
+            end
+            @stream.send(answer)
+
+            true  # handled
+
+          else
+            false # not handled
+          end
+        end
+      end
+
+      ##
+      # Add a feature
+      # feature:: [Jabber::Discovery::Feature] or [String]
+      def add_feature(feature)
+        if feature.kind_of? Feature
+          @features << feature
+        else
+          @features << Feature.new(feature.to_s)
+        end
+      end
+
+      ##
+      # Add a series of features
+      # features:: Array of [Jabber::Discovery::Feature] or [String]
+      def add_features(features)
+        features.each { |feature|
+          add_feature(feature)
+        }
+      end
+
+      ##
+      # Generate a XEP-0115: Entity Capabilities <c/> element
+      # for inclusion in Presence stanzas. This enables efficient
+      # caching of Service Discovery information.
+      def generate_caps
+        Caps::C.new(@node, generate_ver)
+      end
+
+      ##
+      # Generate an item for inclusion in items discovery in other
+      # responders
+      # return:: [Discovery::Item] or nil
+      def generate_item
+        i = @identities.first
+        if i
+          Item.new(@my_jid || @stream.jid, i.iname, @node)
+        else
+          nil
+        end
+      end
+
+      private
+
+      def generate_ver
+        Caps::generate_ver(@identities, @features, @forms)
+      end
+    end
+  end
+end

data/lib/xmpp4r/discovery/iq/discoinfo.rb

@@ -0,0 +1,211 @@
+# =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/query'
+
+module Jabber
+  module Discovery
+    NS_DISCO_INFO = 'http://jabber.org/protocol/disco#info'
+
+    ##
+    # Class for handling Service Discovery queries,
+    # info
+    # (JEP 0030)
+    #
+    # This <query/> may contain multiple Identity and Feature
+    # elements, describing the type and the supported namespaces of
+    # the service.
+    class IqQueryDiscoInfo < IqQuery
+      name_xmlns 'query', NS_DISCO_INFO
+
+      ##
+      # Get the queried Service Discovery node or nil
+      #
+      # See IqQueryDiscoItems#node for a
+      # small explanation of this.
+      def node
+        attributes['node']
+      end
+
+      ##
+      # Set the queried Service Discovery node or nil
+      # val:: [String]
+      def node=(val)
+        attributes['node'] = val
+      end
+
+      ##
+      # Set the queried Service Discovery node or nil
+      # (chaining-friendly)
+      # val:: [String]
+      def set_node(val)
+        self.node = val
+        self
+      end
+
+      ##
+      # Get the first identity child
+      # result:: [Identity]
+      def identity
+        first_element('identity')
+      end
+
+      ##
+      # Get list of identities
+      # result:: [Array] of [Identity]
+      def identities
+        get_elements('identity')
+      end
+
+      ##
+      # Get list of features
+      # result:: [Array] of [String]
+      def features
+        res = []
+        each_element('feature') { |feature|
+          res.push(feature.var)
+        }
+        res
+      end
+    end
+
+
+    ##
+    # Service Discovery identity to add() to IqQueryDiscoInfo
+    #
+    # Please note that XEP 0030 requires both category and type to occur,
+    # for a reference see: http://www.xmpp.org/registrar/disco-categories.html
+    class Identity < XMPPElement
+      name_xmlns 'identity', NS_DISCO_INFO
+
+      ##
+      # Initialize a new Identity
+      # category:: [String] Initial category or nil
+      # iname:: [String] Initial identity name or nil
+      # type:: [String] Initial type or nil
+      def initialize(category=nil, iname=nil, type=nil)
+        super()
+        set_category(category)
+        set_iname(iname)
+        set_type(type)
+      end
+
+      ##
+      # Get the identity's category or nil
+      # result:: [String]
+      def category
+        attributes['category']
+      end
+
+      ##
+      # Set the identity's category
+      #
+      # Service Discovery categories should be somewhat
+      # standardized by some registry, so clients may
+      # represent specific categories by specific icons...
+      # (see http://www.jabber.org/registrar/disco-categories.html)
+      # val:: [String]
+      def category=(val)
+        attributes['category'] = val
+      end
+
+      ##
+      # Set the identity's category (chaining-friendly)
+      # val:: [String]
+      def set_category(val)
+        self.category = val
+        self
+      end
+
+      ##
+      # Get the identity's name or nil
+      #
+      # This has been renamed from <name/> to "iname" here
+      # to keep REXML::Element#name accessible
+      # result:: [String]
+      def iname
+        attributes['name']
+      end
+
+      ##
+      # Set the identity's name
+      # val:: [String]
+      def iname=(val)
+        attributes['name'] = val
+      end
+
+      ##
+      # Set the identity's name (chaining-friendly)
+      # val:: [String]
+      def set_iname(val)
+        self.iname = val
+        self
+      end
+
+      ##
+      # Get the identity's type or nil
+      # result:: [String]
+      def type
+        attributes['type']
+      end
+
+      ##
+      # Set the identity's type
+      # (see http://www.jabber.org/registrar/disco-categories.html)
+      # val:: [String]
+      def type=(val)
+        attributes['type'] = val
+      end
+
+      ##
+      # Set the identity's type (chaining-friendly)
+      # val:: [String]
+      def set_type(val)
+        self.type = val
+        self
+      end
+    end
+
+    ##
+    # Service Discovery feature to add() to IqQueryDiscoInfo
+    #
+    # Please note that JEP 0030 requires var to be set,
+    # for a reference see: http://www.xmpp.org/registrar/disco-features.html
+    class Feature < XMPPElement
+      name_xmlns 'feature', NS_DISCO_INFO
+
+      ##
+      # Create a new <feature/> element
+      # var:: [String] New var
+      def initialize(var=nil)
+        super()
+        set_var(var)
+      end
+
+      ##
+      # Get the feature's var or nil
+      # result:: [String]
+      def var
+        attributes['var']
+      end
+
+      ##
+      # Set the feature's var
+      #
+      # This is a namespace the identity supports.
+      # val:: [String]
+      def var=(val)
+        attributes['var'] = val
+      end
+
+      ##
+      # Set the feature's var (chaining-friendly)
+      # val:: [String]
+      def set_var(val)
+        self.var = val
+        self
+      end
+    end
+  end
+end

data/lib/xmpp4r/discovery/iq/discoitems.rb

@@ -0,0 +1,147 @@
+# =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/query'
+
+module Jabber
+  module Discovery
+    NS_DISCO_ITEMS = 'http://jabber.org/protocol/disco#items'
+
+    ##
+    # Class for handling Service Discovery queries,
+    # items
+    # (JEP 0030)
+    #
+    # This <query/> may contain multiple Item elements,
+    # describing multiple services to be browsed by Jabber clients.
+    # These may then get further information about these items by
+    # querying IqQueryDiscoInfo and further sub-items by querying
+    # IqQueryDiscoItems.
+    class IqQueryDiscoItems < IqQuery
+      name_xmlns 'query', NS_DISCO_ITEMS
+
+      ##
+      # Get the queried Service Discovery node or nil
+      #
+      # A Service Discovery node is _not_ a JID node,
+      # this may be a bit confusing. It's just to make
+      # Service Discovery browsing a bit more structured.
+      def node
+        attributes['node']
+      end
+
+      ##
+      # Set the queried Service Discovery node or nil
+      def node=(val)
+        attributes['node'] = val
+      end
+
+      ##
+      # Set the queried Service Discovery node or nil
+      # (chaining-friendly)
+      def set_node(val)
+        self.node = val
+        self
+      end
+
+      ##
+      # Get all item children
+      # result:: Array of [Discovery::Item]
+      def items
+        get_elements('item')
+      end
+    end
+
+
+    ##
+    # Service Discovery item to add() to IqQueryDiscoItems
+    #
+    # Please note that JEP 0030 requires the jid to occur
+    class Item < XMPPElement
+      name_xmlns 'item', NS_DISCO_ITEMS
+
+      ##
+      # Initialize a new Service Discovery <item/>
+      # to be added to IqQueryDiscoItems
+      # jid:: [JID]
+      # iname:: [String] Item name
+      # node:: [String] Service Discovery node (_not_ JID#node)
+      def initialize(jid=nil, iname=nil, node=nil)
+        super()
+        set_jid(jid)
+        set_iname(iname)
+        set_node(node)
+      end
+
+      ##
+      # Get the item's jid or nil
+      # result:: [String]
+      def jid
+        JID.new(attributes['jid'])
+      end
+
+      ##
+      # Set the item's jid
+      # val:: [JID]
+      def jid=(val)
+        attributes['jid'] = val.to_s
+      end
+
+      ##
+      # Set the item's jid (chaining-friendly)
+      # val:: [JID]
+      def set_jid(val)
+        self.jid = val
+        self
+      end
+
+      ##
+      # Get the item's name or nil
+      #
+      # This has been renamed from <name/> to "iname" here
+      # to keep REXML::Element#name accessible
+      # result:: [String]
+      def iname
+        attributes['name']
+      end
+
+      ##
+      # Set the item's name
+      # val:: [String]
+      def iname=(val)
+        attributes['name'] = val
+      end
+
+      ##
+      # Set the item's name (chaining-friendly)
+      # val:: [String]
+      def set_iname(val)
+        self.iname = val
+        self
+      end
+
+      ##
+      # Get the item's Service Discovery node or nil
+      # result:: [String]
+      def node
+        attributes['node']
+      end
+
+      ##
+      # Set the item's Service Discovery node
+      # val:: [String]
+      def node=(val)
+        attributes['node'] = val
+      end
+
+      ##
+      # Set the item's Service Discovery node (chaining-friendly)
+      # val:: [String]
+      def set_node(val)
+        self.node = val
+        self
+      end
+    end
+  end
+end