mojodna-xmpp4r 0.4.0.2

data/lib/xmpp4r/tune/tune.rb

@@ -0,0 +1,113 @@
+# =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'
+require 'rexml/element'
+
+module Jabber
+  module UserTune
+    NS_USERTUNE = 'http://jabber.org/protocol/tune'
+
+    ##
+    # The <tune> XMPP element, as defined in XEP-0118 User Tune
+    #
+    # See http://www.xmpp.org/extensions/xep-0118.html - this element
+    # encapsulates metadata (artist, track etc) about a tune the user
+    # is currently playing. These are expressed as child elements
+    # such as <artist>, <title> etc which are also managed by this class.
+    #
+    # If the element has no children then it indicates that the user
+    # has stopped playing a tune. Use the Tune#playing? method to discover
+    # this?
+    class Tune < XMPPElement
+      name_xmlns 'tune', NS_USERTUNE
+      force_xmlns true
+
+      ##
+      # Construct a new <tune> element.
+      #
+      # Supply no arguments to make an
+      # empty element to indicate that tune playing has stopped.
+      #
+      # artist:: [String] the artist or performer of the song or piece
+      # title:: [String] the title of the song or piece
+      # length:: [Fixnum] the duration of the song or piece in seconds
+      # track:: [String] a unique identifier for the tune; e.g., the track number within a collection or the specific URI for the object (e.g., a stream or audio file)
+      # source:: [String] the collection (e.g., album) or other source (e.g., a band website that hosts streams or audio files)
+      # uri:: [String] a URI or URL pointing to information about the song, collection, or artist
+      # rating:: [Numeric] a number indicating how much you like this song - will be clamped into an integer 0 <= x <= 10
+      def initialize(artist = nil, title = nil, length = nil, track = nil, source = nil, uri = nil, rating = nil)
+        super()
+
+        add_element(REXML::Element.new('artist')).text = artist if artist
+
+        add_element(REXML::Element.new('title')).text = title if title
+
+        add_element(REXML::Element.new('length')).text = length.to_s if length
+
+        add_element(REXML::Element.new('track')).text = track if track
+
+        add_element(REXML::Element.new('source')).text = source if source
+
+        add_element(REXML::Element.new('uri')).text = uri if uri
+
+        if rating and rating.kind_of?(Numeric)
+          r = rating.to_i
+          r = 0 if r < 0
+          r = 10 if r > 10
+          add_element(REXML::Element.new('rating')).text = r.to_s
+        end
+      end
+
+
+      ##
+      # Returns true if a tune is currently playing, otherwise false.
+      def playing?
+        (elements.size > 0)
+      end
+
+      ##
+      # Get the artist for this tune.
+      def artist
+        first_element('artist').text if first_element('artist')
+      end
+
+      ##
+      # Get the title of this tune.
+      def title
+        first_element('title').text  if first_element('title')
+      end
+
+      ##
+      # Get the length of this tune, in seconds.
+      def length
+        first_element('length').text.to_i if first_element('length')
+      end
+
+      ##
+      # Get an identitier for this tune.
+      def track
+        first_element('track').text if first_element('track')
+      end
+
+      ##
+      # Get the source of this tune, such as an album.
+      def source
+        first_element('source').text if first_element('source')
+      end
+
+      ##
+      # Get a URI that represents this tune.
+      def uri
+        first_element('uri').text if first_element('uri')
+      end
+
+      ##
+      # Get the rating for this track
+      def rating
+        first_element('rating').text.to_i if first_element('rating')
+      end
+    end
+  end
+end

data/lib/xmpp4r/tune.rb

@@ -0,0 +1,2 @@
+require 'xmpp4r/tune/tune'
+require 'xmpp4r/tune/helper/helper'

data/lib/xmpp4r/vcard/helper/vcard.rb

@@ -0,0 +1,84 @@
+# =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
+    ##
+    # The Vcard helper retrieves vCards
+    class Helper
+      ##
+      # Initialize a new Vcard helper
+      def initialize(stream)
+        @stream = stream
+      end
+
+      ##
+      # Retrieve vCard of an entity
+      #
+      # Raises exception upon retrieval error, please catch that!
+      # (The exception is ServerError and is raisen by
+      # Stream#send_with_id.
+      #
+      # Usage of Threads is suggested here as vCards can be very
+      # big (see <tt>/iq/vCard/PHOTO/BINVAL</tt>).
+      #
+      # jid:: [Jabber::JID] or nil (should be stripped, nil for the client's own vCard)
+      # result:: [Jabber::IqVcard] or nil (nil results may be handled as empty vCards)
+      def get(jid=nil)
+        res = nil
+        request = Iq.new(:get, jid)
+        request.from = @stream.jid  # Enable components to use this
+        request.add(IqVcard.new)
+        @stream.send_with_id(request) { |answer|
+          # No check for sender or queryns needed (see send_with_id)
+          if answer.type == :result
+            res = answer.vcard
+            true
+          else
+            false
+          end
+        }
+        res
+      end
+
+      ##
+      # Set your own vCard (Clients only)
+      #
+      # Raises exception when setting fails
+      #
+      # Usage of Threads suggested here, too. The function
+      # waits for approval from the server.
+      #
+      # iqvcard:: [Jabber::IqVcard]
+      def set(iqvcard)
+        iq = Iq.new(:set)
+        iq.add(iqvcard)
+
+        @stream.send_with_id(iq) { |answer|
+          if answer.type == :result
+            true
+          else
+            false
+          end
+        }
+      end
+
+      ##
+      # Quickly initialize a Vcard helper and get
+      # a vCard. See Vcard#get
+      def self.get(stream, jid=nil)
+        new(stream).get(jid)
+      end
+
+      ##
+      # Quickly initialize a Vcard helper and set
+      # your vCard. See Vcard#set
+      def self.set(stream, iqvcard)
+        new(stream).set(iqvcard)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# =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/base64'
+
+module Jabber
+  module Vcard
+    ##
+    # vCard container for User Information
+    # (can be specified by users themselves, mostly kept on servers)
+    # (JEP 0054)
+    class IqVcard < XMPPElement
+      name_xmlns 'vCard', 'vcard-temp'
+      force_xmlns true
+
+      ##
+      # Initialize a <vCard/> element
+      # fields:: [Hash] Initialize with keys as XPath element names and values for element texts
+      def initialize(fields=nil)
+        super()
+
+        unless fields.nil?
+          fields.each { |name,value|
+            self[name] = value
+          }
+        end
+      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
+
+      ##
+      # Get the PHOTO/BINVAL (Avatar picture) field decoded from Base64
+      # result:: [String] or [nil]
+      def photo_binval
+        if (binval = self['PHOTO/BINVAL'])
+          Base64::decode64(binval)
+        else
+          nil
+        end
+      end
+
+      private
+
+      ##
+      # 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
+    end
+  end
+end

data/lib/xmpp4r/vcard.rb

@@ -0,0 +1,6 @@
+# =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/vcard/helper/vcard.rb'
+require 'xmpp4r/vcard/iq/vcard.rb'

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

@@ -0,0 +1,72 @@
+# =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 '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)
+              true
+            }
+            @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,105 @@
+# =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
+      name_xmlns 'query', 'jabber:iq:version'
+
+      ##
+      # Create a new <query xmlns='jabber:iq:version'/> element
+      def initialize(iname=nil, version=nil, os=nil)
+        super()
+        set_iname(iname) if iname
+        set_version(version) if version
+        set_os(os) if os
+      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
+  end
+end

data/lib/xmpp4r/version.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/version/helper/responder.rb'
+require 'xmpp4r/version/helper/simpleresponder.rb'
+require 'xmpp4r/version/iq/version.rb'

data/lib/xmpp4r/x.rb

@@ -0,0 +1,37 @@
+# =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 <x/> elements
+  #
+  # These elements may occur as "attachments"
+  # in [Message] and [Presence] stanzas
+  class X < XMPPElement
+    name_xmlns 'x'
+    force_xmlns true
+  end
+
+  module XParent
+    ##
+    # Get the first <x/> element in this stanza, or nil if none found.
+    # wanted_xmlns:: [String] Optional, find the first <x/> element having this xmlns,
+    # wanted_xmlns can also be a derivate of XMPPElement from which the namespace will be taken
+    # result:: [REXML::Element] or nil
+    def x(wanted_xmlns=nil)
+      if wanted_xmlns.kind_of? Class and wanted_xmlns.ancestors.include? XMPPElement
+        wanted_xmlns = wanted_xmlns.new.namespace
+      end
+
+        each_element('x') { |x|
+        if wanted_xmlns.nil? or wanted_xmlns == x.namespace
+          return x
+        end
+      }
+      nil
+    end
+  end
+end

data/lib/xmpp4r/xhtml/html.rb

@@ -0,0 +1,115 @@
+require 'xmpp4r/xmppelement'
+
+module Jabber
+  module XHTML
+    NS_XHTML_IM = 'http://jabber.org/protocol/xhtml-im'
+    NS_XHTML = 'http://www.w3.org/1999/xhtml'
+
+    ##
+    # XHTML-IM (XEP-0071) container
+    #
+    # The important methods are:
+    # * HTML#contents=
+    # * HTML#to_text
+    class HTML < XMPPElement
+      name_xmlns 'html', NS_XHTML_IM
+      force_xmlns true
+
+      ##
+      # Initialize element with HTML contents (see HTML#contents=)
+      def initialize(contents=[])
+        super()
+        self.contents = contents
+      end
+
+      ##
+      # Get first XHTML::Body child
+      def body
+        first_element('body') || add(Body.new)
+      end
+
+      ##
+      # Replace first XHTML::Body child
+      def body=(body)
+        delete_elements('body')
+        add(body)
+      end
+
+      ##
+      # Replace first XHTML::Body child (chainable)
+      def set_body(body)
+        self.body = body
+        self
+      end
+
+      ##
+      # Set contents of this HTML document. The "contents" parameter can be:
+      # * An Array of REXML::Element and Strings which will replace the current children of the body
+      # * A single REXML::Element which will replace all other children of the body
+      # * An instance of XHTML::Body which will replace the current body
+      # * A String comprising an HTML fragment. This will be parsed, which could raise an Exception.
+      #   We must never send invalid XML over an XMPP stream. If you intend to put variable data in
+      #   your HTML, use something like Rails' Builder::XmlMarkup or Ramaze::Gestalt
+      def contents=(contents)
+        if contents.kind_of? String
+          self.body = REXML::Document.new("<body xmlns='#{NS_XHTML}'>#{contents}</body>").root
+        elsif contents.kind_of? Body
+          self.body = contents
+        elsif contents.kind_of? Array
+          self.body = Body.new
+          contents.each do |element|
+            if element.kind_of? String
+              body.add_text(element)
+            else
+              body.add(element)
+            end
+          end
+        else
+          self.body = Body.new
+          body.add(contents)
+        end
+      end
+
+      ##
+      # HTML#contents= chainable
+      def set_contents(contents)
+        self.contents = contents
+        self
+      end
+
+      ##
+      # Convert contents of this XHTML container to plain text
+      # for easy usage with an additional fall-back <body/> in message stanzas
+      #
+      # The resulting string is recursively composed of the text nodes of
+      # all children.
+      # This works because of the design criteria of HTML/XHTML:
+      # readable content is not being put into attributes but as text children.
+      #
+      # If you require clickable links and proper information representation
+      # then compose the text yourself!
+      def to_text
+        text_getter = nil # Create binding so that the following lambda can work recursively
+
+        text_getter = lambda do |element|
+          if element.kind_of? REXML::Text
+            element.value
+          elsif element.kind_of? REXML::Element
+            element.children.collect { |child|
+              text_getter.call(child)
+            }.join
+          end
+        end
+
+        text_getter.call(self) # Finally, execute and return results
+      end
+    end
+
+    ##
+    # HTML Body element, must be the only child of XHTML::HTML
+    class Body < XMPPElement
+      name_xmlns 'body', NS_XHTML
+      force_xmlns true
+    end
+  end
+end

data/lib/xmpp4r/xhtml.rb

@@ -0,0 +1 @@
+require 'xmpp4r/xhtml/html'