xmpp4r 0.3

data/lib/xmpp4r/vcard/iq/vcard.rb

@@ -0,0 +1,102 @@
+# =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 Vcard
+    ##
+    # vCard container for User Information
+    # (can be specified by users themselves, mostly kept on servers)
+    # (JEP 0054)
+    class IqVcard < REXML::Element
+      ##
+      # Initialize a <vCard/> element
+      # fields:: [Hash] Initialize with keys as XPath element names and values for element texts
+      def initialize(fields=nil)
+        super("vCard")
+        add_namespace('vcard-temp')
+
+        unless fields.nil?
+          fields.each { |name,value|
+            self[name] = value
+          }
+        end
+      end
+
+      ##
+      # element:: [REXML::Element] to import
+      # result:: [IqVcard] with all attributes and children copied from element
+      def IqVcard.import(element)
+        IqVcard::new.import(element)
+      end
+
+      ##
+      # Get an elements/fields text
+      #
+      # vCards have too much possible children, so ask for them here
+      # and extract the result with iqvcard.element('...').text
+      # name:: [String] XPath
+      def [](name)
+        text = nil
+        each_element(name) { |child| text = child.text }
+        text
+      end
+
+      ##
+      # Set an elements/fields text
+      # name:: [String] XPath
+      # text:: [String] Value
+      def []=(name, text)
+        xe = self
+        name.split(/\//).each do |elementname|
+          # Does the children already exist?
+          newxe = nil
+          xe.each_element(elementname) { |child| newxe = child }
+
+          if newxe.nil?
+            # Create a new
+            xe = xe.add_element(elementname)
+          else
+            # Or take existing
+            xe = newxe
+          end
+        end
+        xe.text = text
+      end
+
+      ##
+      # Get vCard field names
+      #
+      # Example:
+      #  ["NICKNAME", "BDAY", "ORG/ORGUNIT", "PHOTO/TYPE", "PHOTO/BINVAL"]
+      #
+      # result:: [Array] of [String]
+      def fields
+        element_names(self).uniq
+      end
+
+      ##
+      # Recursive helper function,
+      # returns all element names in an array, concatenated
+      # to their parent's name with a slash
+      def element_names(xe, prefix='')  # :nodoc:
+        res = []
+        xe.each_element { |child|
+          if child.kind_of?(REXML::Element)
+            children = element_names(child, "#{prefix}#{child.name}/")
+            if children == []
+              res.push("#{prefix}#{child.name}")
+            else
+              res += children
+            end
+          end
+        }
+        res
+      end
+
+      Iq.add_elementclass('vCard', IqVcard)
+    end
+  end
+end

data/lib/xmpp4r/vcard.rb

@@ -0,0 +1,3 @@
+require 'xmpp4r/vcard/helper/vcard.rb'
+require 'xmpp4r/vcard/iq/vcard.rb'
+

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

@@ -0,0 +1,71 @@
+# =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 'callbacks'
+require 'xmpp4r/version/iq/version'
+
+module Jabber
+  module Version
+    ##
+    # A class to answer version requests using IqQueryVersion
+    #
+    # If you don't need the flexibility of dynamic responses with
+    # the callback you can register with add_version_callback,
+    # take a look at SimpleResponder
+    class Responder
+      ##
+      # Initialize a new version responder
+      #
+      # Registers it's callback (prio = 180, ref = self)
+      # stream:: [Stream] Where to register callback handlers
+      def initialize(stream)
+        @stream = stream
+        @versioncbs = CallbackList.new
+
+        stream.add_iq_callback(180, self) { |iq|
+          iq_callback(iq)
+        }
+      end
+
+      ##
+      # Add a callback for Iq stanzas with IqQueryVersion
+      #
+      # First argument passed to block is the Iq stanza,
+      # second argument is a block, which can be called with
+      # software name, version and os
+      #
+      # Example:
+      #   my_version_helper.add_version_callback { |iq,block|
+      #     block.call('Cool client', '6.0', 'Cool OS')
+      #   }
+      def add_version_callback(priority = 0, ref = nil, &block)
+        @versioncbs.add(priority, ref, block)
+      end
+
+      ##
+      # <iq/> callback handler to answer Software Version queries
+      # (registered by constructor and used internally only)
+      #
+      # Used internally
+      def iq_callback(iq)
+        if iq.type == :get
+          if iq.query.kind_of?(IqQueryVersion)
+            replyblock = lambda { |name,version,os|
+              answer = iq.answer
+              answer.type = :result
+              answer.query.set_iname(name).set_version(version).set_os(os)
+
+              @stream.send(answer)
+            }
+            @versioncbs.process(iq, replyblock)
+          else
+            false
+          end
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/xmpp4r/version/helper/simpleresponder.rb

@@ -0,0 +1,44 @@
+# =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/version/helper/responder'
+
+module Jabber
+  module Version
+    ##
+    # A class to answer version requests using IqQueryVersion
+    #
+    # This is simplification as one doesn't need dynamic
+    # version answering normally.
+    #
+    # Example usage:
+    #  Jabber::Version::SimpleResponder.new(my_client, "My cool XMPP4R script", "1.0", "Younicks")
+    class SimpleResponder < Responder
+      attr_accessor :name
+      attr_accessor :version
+      attr_accessor :os
+
+      ##
+      # Initialize a new version responder
+      #
+      # Registers it's callback (prio = 180, ref = self)
+      # stream:: [Stream] Where to register callback handlers
+      # name:: [String] Software name for answers
+      # version:: [String] Software versio for answers
+      # os:: [String] Optional operating system name for answers
+      def initialize(stream, name, version, os=nil)
+        super stream
+
+        @name = name
+        @version = version
+        @os = os
+
+        add_version_callback(180, self) { |iq,block|
+          block.call(@name, @version, @os)
+        }
+      end
+    end
+  end
+end

data/lib/xmpp4r/version/iq/version.rb

@@ -0,0 +1,118 @@
+# =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 Version
+    ##
+    # Class for handling queries for 'Software Version'
+    # (JEP 0092)
+    #
+    # Notice that according to JEP 0092 only the <os/> element can be omitted,
+    # <name/> (iname) and <version/> must be present
+    class IqQueryVersion < IqQuery
+      ##
+      # Create a new <query xmlns='jabber:iq:version'/> element
+      def initialize(iname='', version='', os=nil)
+        super()
+        add_namespace('jabber:iq:version')
+        set_iname(iname)
+        set_version(version)
+        set_os(os)
+      end
+
+      ##
+      # Import an element,
+      # deletes <name/>, <version/> and <os/> elements first
+      # xe:: [REXML::Element]
+      def import(xe)
+        delete_element('name')
+        delete_element('version')
+        delete_element('os')
+        super
+      end
+
+      ##
+      # Get the name of the software
+      #
+      # This has been renamed to 'iname' here to keep
+      # REXML::Element#name accessible
+      def iname
+        first_element_text('name')
+      end
+
+      ##
+      # Set the name of the software
+      #
+      # The element won't be deleted if text is nil as
+      # it must occur in a version query, but its text will
+      # be empty.
+      def iname=(text)
+        replace_element_text('name', text.nil? ? '' : text)
+      end
+
+      ##
+      # Set the name of the software (chaining-friendly)
+      # result:: [String] or nil
+      def set_iname(text)
+        self.iname = text
+        self
+      end
+
+      ##
+      # Get the version of the software
+      # result:: [String] or nil
+      def version
+        first_element_text('version')
+      end
+
+      ##
+      # Set the version of the software
+      #
+      # The element won't be deleted if text is nil as
+      # it must occur in a version query
+      def version=(text)
+        replace_element_text('version', text.nil? ? '' : text)
+      end
+
+      ##
+      # Set the version of the software (chaining-friendly)
+      # text:: [String]
+      def set_version(text)
+        self.version = text
+        self
+      end
+
+      ##
+      # Get the operating system or nil
+      # (os is not mandatory for Version Query)
+      def os
+        first_element_text('os')
+      end
+
+      ##
+      # Set the os of the software
+      # text:: [String] or nil
+      def os=(text)
+        if text
+          replace_element_text('os', text)
+        else
+          delete_elements('os')
+        end
+      end
+
+      ##
+      # Set the os of the software (chaining-friendly)
+      # text:: [String] or nil
+      def set_os(text)
+        self.os = text
+        self
+      end
+    end
+
+    IqQuery.add_namespaceclass('jabber:iq:version', IqQueryVersion)
+  end
+end
+

data/lib/xmpp4r/version.rb

@@ -0,0 +1,3 @@
+require 'xmpp4r/version/helper/responder.rb'
+require 'xmpp4r/version/helper/simpleresponder.rb'
+require 'xmpp4r/version/iq/version.rb'

data/lib/xmpp4r/x.rb

@@ -0,0 +1,43 @@
+# =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/rexmladdons'
+
+module Jabber
+  ##
+  # A class used to build/parse <x/> elements
+  #
+  # These elements may occur as "attachments"
+  # in [Message] and [Presence] stanzas
+  class X < REXML::Element
+    @@namespace_classes = {}
+
+    ##
+    # Initialize a <x/> element
+    #
+    # Does nothing more than setting the element's name to 'x'
+    def initialize
+      super("x")
+    end
+
+    ##
+    # Create a new [X] from an XML-Element
+    # element:: [REXML::Element] to import, will be automatically converted if namespace appropriate
+    def X.import(element)
+      if @@namespace_classes.has_key?(element.namespace)
+        @@namespace_classes[element.namespace]::new.import(element)
+      else
+        X::new.import(element)
+      end
+    end
+
+    ##
+    # Add a class by namespace for automatic X conversion (see X.import)
+    # ns:: [String] Namespace (e.g. 'jabber:x:delay')
+    # xclass:: [X] x class derived from X
+    def X.add_namespaceclass(ns, xclass)
+      @@namespace_classes[ns] = xclass
+    end
+  end
+end

data/lib/xmpp4r/xmlstanza.rb

@@ -0,0 +1,174 @@
+# =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/jid'
+require 'xmpp4r/error'
+
+module Jabber
+  ##
+  # root class of all Jabber XML elements
+  class XMLStanza < REXML::Element
+    ##
+    # Compose a response by doing the following:
+    # * Create a new XMLStanza of the same subclass
+    #   with the same element-name
+    # * Import xmlstanza if import is true
+    # * Swap 'to' and 'from'
+    # * Copy 'id'
+    # * Does not take care about the type
+    #
+    # *Attention*: Be careful when answering to stanzas with
+    # <tt>type == :error</tt> - answering to an error may generate
+    # another error on the other side, which could be leading to a
+    # ping-pong effect quickly!
+    #
+    # xmlstanza:: [XMLStanza] source
+    # import:: [true or false] Copy attributes and children of source
+    # result:: [XMLStanza] answer stanza
+    def XMLStanza.answer(xmlstanza, import=true)
+      x = xmlstanza.class::new
+      if import
+        x.import(xmlstanza)
+      end
+      x.from = xmlstanza.to
+      x.to = xmlstanza.from
+      x.id = xmlstanza.id
+      x
+    end
+
+    ##
+    # Add a sub-element
+    #
+    # Will be converted to [Error] if named "error"
+    # element:: [REXML::Element] to add
+    def typed_add(element)
+      if element.kind_of?(REXML::Element) && (element.name == 'error')
+        super(Error::import(element))
+      else
+        super(element)
+      end
+    end
+
+    ##
+    # Return the first <tt><error/></tt> child
+    def error
+      first_element('error')
+    end
+
+    ##
+    # Compose a response of this XMLStanza
+    # (see XMLStanza.answer)
+    # result:: [XMLStanza] New constructed stanza
+    def answer(import=true)
+      XMLStanza.answer(self, import)
+    end
+
+    ##
+    # Makes some changes to the structure of an XML element to help
+    # it respect the specification. For example, in a message, we should
+    # have <subject/> < <body/> < { rest of tags }
+    def normalize
+    end
+
+    ##
+    # get the to attribute
+    #
+    # return:: [String] the element's to attribute
+    def to
+      (a = attribute('to')).nil? ? a : JID::new(a.value)
+    end
+
+    ##
+    # set the to attribute
+    #
+    # v:: [String] the value to set
+    def to= (v)
+      add_attribute('to', v ? v.to_s : nil)
+    end
+
+    ##
+    # set the to attribute (chaining-friendly)
+    #
+    # v:: [String] the value to set
+    def set_to(v)
+      self.to = v
+      self
+    end
+
+    ##
+    # get the from attribute
+    #
+    # return:: [String] the element's from attribute
+    def from
+      (a = attribute('from')).nil? ? a : JID::new(a.value)
+    end
+
+    ##
+    # set the from attribute
+    #
+    # v:: [String] the value from set
+    def from= (v)
+      add_attribute('from', v ? v.to_s : nil)
+    end
+
+    ##
+    # set the from attribute (chaining-friendly)
+    #
+    # v:: [String] the value from set
+    def set_from(v)
+      add_attribute('from', v ? v.to_s : nil)
+      self
+    end
+
+    ##
+    # get the id attribute
+    #
+    # return:: [String] the element's id attribute
+    def id
+      (a = attribute('id')).nil? ? a : a.value
+    end
+
+    ##
+    # set the id attribute
+    #
+    # v:: [String] the value id set
+    def id= (v)
+      add_attribute('id', v)
+    end
+
+    ##
+    # set the id attribute (chaining-friendly)
+    #
+    # v:: [String] the value id set
+    def set_id(v)
+      add_attribute('id', v)
+      self
+    end
+
+    ##
+    # get the type attribute
+    #
+    # return:: [String] the element's type attribute
+    def type
+      (a = attribute('type')).nil? ? a : a.value
+    end
+
+    ##
+    # set the type attribute
+    #
+    # v:: [String] the value type set
+    def type= (v)
+      add_attribute('type', v)
+    end
+
+    ##
+    # set the type attribute (chaining-friendly)
+    #
+    # v:: [String] the value type set
+    def set_type(v)
+      add_attribute('type', v)
+      self
+    end
+  end
+end

data/lib/xmpp4r/xmpp4r.rb

@@ -0,0 +1,16 @@
+# =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/
+
+##
+# The Jabber module is the root namespace of the library. You might want
+# to Include it in your script to ease your coding. It provides
+# a simple debug logging support.
+module Jabber
+  # XMPP4R Version number
+  XMPP4R_VERSION = '0.3'
+end
+
+require 'xmpp4r/client'
+require 'xmpp4r/component'
+require 'xmpp4r/debuglog'

data/lib/xmpp4r.rb

@@ -0,0 +1,122 @@
+# =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/
+#
+# ==Introduction
+#
+# XMPP4R is a XMPP/Jabber library for Ruby. It can be used to build scripts
+# using Jabber, full-featured Jabber clients, and components. It is written
+# with extensibility in mind.
+#
+# ==XML management
+#
+# All the XML parsing is REXML's, and XML stanzas like <message/> (class
+# <tt>Jabber::Message</tt>) or <iq/> (class <tt>Jabber::Iq</tt>) are indirect
+# derivatives from REXML's Element class. This provide a maximum flexibity:
+# the user can access attributes and childs using either the XMPP4R's helpers
+# or directly using REXML's methods.
+#
+# ===Automatic element casting
+#
+# Because there are special classes derived from REXML::Element to ease
+# development on the protocol level, Elements must be cast to them. This is
+# done via REXML::Element.import. This method is also used in import class
+# methods of some Element classes.
+#
+# The first occurance of this feature is in Jabber::Stream::receive:
+# * <tt><message/></tt> stanzas are cast to Jabber::Message class
+# * <tt><presence/></tt> stanzas are cast to Jabber::Presence class
+# * <tt><iq/></tt> stanzas are cast to Jabber::Iq class
+#
+# This is not only useful for stanzas but all other XML processing, too:
+# * <tt><x/></tt> children elements of <tt><message/></tt> and <tt><presence/></tt> are converted to Jabber::X
+# * <tt><error/></tt> children elements of all three stanzas are converted to Jabber::Error
+# * <tt><query/></tt> children elements of <tt><iq/></tt> are converted to Jabber::IqQuery
+# * <tt><vCard/></tt> children elements of <tt><iq/></tt> are converted to Jabber::IqVcard
+#
+# The following conversion facilities are only executed if the respective
+# library parts are loaded. See below for more details on Non-basic features.
+# * Jabber::IqQuery elements are converted to Jabber::Roster::IqQueryRoster if their
+#   namespace is 'jabber:iq:roster'
+# * Jabber::IqQuery elements are converted to Jabber::Version::IqQueryVersion if their
+#   namespace is 'jabber:iq:version'
+# * Jabber::IqQuery elements are converted to Jabber::Discovery::IqQueryDiscoInfo if their
+#   namespace is 'http://jabber.org/protocol/disco#info'
+# * Jabber::IqQuery elements are converted to Jabber::Discovery::IqQueryDiscoItems if their
+#   namespace is 'http://jabber.org/protocol/disco#items'
+# * <tt><item/></tt> children elements of Jabber::Roster::IqQueryRoster are converted
+#   to Jabber::Roster::RosterItem
+# * <tt><identity/></tt> children elements of Jabber::IqQueryDiscoInfo are converted
+#   to Jabber::Discovery::DiscoIdentity
+# * <tt><feature/></tt> children elements of Jabber::IqQueryDiscoInfo are converted
+#   to Jabber::Discovery::DiscoFeature
+# * <tt><item/></tt> children elements of Jabber::IqQueryDiscoItems are converted
+#   to Jabber::Discovery::DiscoItem
+#
+# To use this, don't check for:
+# <tt>iq.queryns == 'http://jabber.org/protocol/disco#info'</tt>
+#
+# But instead check for the query's class:
+# <tt>iq.query.kind_of?(Jabber::IqQueryDiscoInfo)</tt>
+#
+# ==Threaded and non-threaded modes
+#
+# From the user's point of view, the library can be used either in threaded mode,
+# or in non-threaded mode, using a call to <tt>Jabber::Stream#process</tt> to
+# receive pending messages.
+#
+# ==Where to begin?
+#
+# Because it is built in an extensible way, it might be hard for newcomers to
+# understand where to look at documentation for a specific method. For example,
+# Client heritates from Connection, which itself heritates from Stream.
+#
+# A newcomer should have a look at the <tt>Jabber::Client</tt> and
+# <tt>Jabber::Component</tt> classes, and their parent classes
+# <tt>Jabber::Connection</tt> and <tt>Jabber::Stream</tt>.  The best way to
+# understand how to use them is probably to look at the examples in the
+# <tt>examples/</tt> dir.
+#
+# ==Non-basic features
+#
+# <tt>require 'xmpp4r'</tt> does only include basic functionality as
+# Connections, Authentication, Stream processing, Callbacks, Stanza handling
+# and Debugging to keep the library's footprint small.
+#
+# There is code for features that aren't required by a *basic* client. These
+# must be additionally included to use them.
+#
+# ===Protocol-level features
+#
+# You're highly advised to read the according RFCs and JEPs if you intend to
+# use them. The benefit will be that you'll understand the protocols and be
+# going to be more efficient when programming with them.
+#
+# * Jabber::Bytestreams, Jabber::FileTransfer: <tt>require 'xmpp4r/bytestreams'</tt>
+# * Jabber::Dataforms: <tt>require 'xmpp4r/dataforms'</tt>
+# * Jabber::Delay: <tt>require 'xmpp4r/delay'</tt>
+# * Jabber::Discovery: <tt>require 'xmpp4r/discovery'</tt>
+# * Jabber::FeatureNegotiation: <tt>require 'xmpp4r/feature_negotiation'</tt>
+# * Jabber::MUC: <tt>require 'xmpp4r/muc'</tt>
+# * Jabber::Roster: <tt>require 'xmpp4r/roster'</tt>
+# * Jabber::Vcard: <tt>require 'xmpp4r/vcard'</tt>
+# * Jabber::Version: <tt>require 'xmpp4r/version'</tt>
+#
+# ===Helpers
+#
+# Helpers are intended to give more simplistic interfaces to various tasks
+# of Jabber clients at the cost of flexibility. But you won't need that
+# order of flexibility for the most things.
+#
+# * Jabber::Roster::Helper: <tt>require 'xmpp4r/roster'</tt>
+# * Jabber::MUC::MUCBrowser, Jabber::MUC::MUCClient, Jabber::MUC::SimpleMUCClient: <tt>require 'xmpp4r/muc'</tt>
+# * Jabber::Version::SimpleResponder, Jabber::Version::Responder: <tt>require 'xmpp4r/version'</tt>
+# * Jabber::Vcard::Helper: <tt>require 'xmpp4r/vcard'</tt>
+# * Jabber::FileTransfer::Helper, Jabber::Bytestreams::SOCKS5BytestreamsServer: <tt>require 'xmpp4r/bytestreams'</tt>
+#
+# ==Debugging
+#
+# Dumping your Jabber stream can be enabled this way:
+#   Jabber::debug = true
+
+require 'xmpp4r/xmpp4r'