UPnP 1.0.0

data/.autotest

@@ -0,0 +1,30 @@
+# vim: filetype=ruby
+
+Autotest.add_hook :initialize do |at|
+
+  at.add_mapping %r%^lib/UPnP/SSDP.rb$% do
+    ['test/test_UPnP_SSDP.rb',
+     'test/test_UPnP_SSDP_notification.rb',
+     'test/test_UPnP_SSDP_response.rb',
+    ]
+  end
+
+  at.add_mapping %r%^lib/UPnP/control/(\w+).rb$% do |_,m|
+    "test/test_UPnP_Control_#{m[1].capitalize}.rb"
+  end
+
+  at.add_mapping %r%^test/utilities.rb$% do
+    at.known_files
+  end
+
+  at.extra_class_map["TestUPnPControlDevice"] =
+    'test/test_UPnP_control_device.rb'
+  at.extra_class_map["TestUPnPSSDP"] = 'test/test_UPnP_SSDP.rb'
+  at.extra_class_map["TestUPnPSSDPNotification"] =
+    'test/test_UPnP_SSDP_notification.rb'
+  at.extra_class_map["TestUPnPSSDPResponse"] =
+    'test/test_UPnP_SSDP_response.rb'
+  at.extra_class_map["TestUPnPControlService"] =
+    'test/test_UPnP_control_service.rb'
+end
+

data/History.txt

@@ -0,0 +1,6 @@
+=== 1.0.0 / 2008-06-25
+
+* 1 major enhancement
+
+  * Birthday!
+

data/Manifest.txt

@@ -0,0 +1,18 @@
+.autotest
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/upnp_discover
+bin/upnp_listen
+lib/UPnP.rb
+lib/UPnP/SSDP.rb
+lib/UPnP/control.rb
+lib/UPnP/control/device.rb
+lib/UPnP/control/service.rb
+test/test_UPnP_SSDP.rb
+test/test_UPnP_SSDP_notification.rb
+test/test_UPnP_SSDP_response.rb
+test/test_UPnP_control_device.rb
+test/test_UPnP_control_service.rb
+test/utilities.rb

data/README.txt

@@ -0,0 +1,95 @@
+= UPnP
+
+* http://seattlerb.org/UPnP
+* http://upnp.org
+* Bugs: http://rubyforge.org/tracker/?atid=5921&group_id=1513
+
+== DESCRIPTION:
+
+An implementation of the UPnP protocol
+
+== FEATURES/PROBLEMS:
+
+* Discovers UPnP devices and services via SSDP, see UPnP::SSDP
+* Creates a SOAP RPC driver for discovered services, see UPnP::Control::Service
+* Creates concrete UPnP device and service classes that may be extended with
+  utility methods, see UPnP::Control::Device::create,
+  UPnP::Control::Service::create and the UPnP-IGD gem.
+* Eventing not implemented
+* Servers not implemented
+
+== SYNOPSIS:
+
+Print out information about UPnP devices nearby:
+
+  upnp_discover
+
+Listen for UPnP resource notifications:
+
+  upnp_listen
+
+Search for root UPnP devices and print out their description URLs:
+
+  require 'UPnP/SSDP'
+  
+  resources = UPnP::SSDP.new.search :root
+  locations = resources.map { |resource| resource.location }
+  puts locations.join("\n")
+
+Create a UPnP::Control::Device from the first discovered root device:
+
+  require 'UPnP/control/device'
+  
+  device = UPnP::Control::Device.create locations.first
+
+Enumerate actions on all services on the device:
+
+  service_names = device.services.map do |service|
+    service.methods(false)
+  end
+  
+  puts service_names.sort.join("\n")
+
+Assuming the root device is an InternetGatewayDevice with a WANIPConnection
+service, print out the external IP address for the gateway:
+
+  wic = device.services.find { |service| service.type =~ /WANIPConnection/ }
+  puts wic.GetExternalIPAddress
+
+== REQUIREMENTS:
+
+* UPnP devices
+
+== INSTALL:
+
+  sudo gem install UPnP
+
+== LICENSE:
+
+All code copyright 2008 Eric Hodel.  All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither the names of the authors nor the names of their contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
+OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/Rakefile

@@ -0,0 +1,12 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/upnp.rb'
+
+Hoe.new('UPnP', UPnP::VERSION) do |p|
+  p.rubyforge_name = 'seattlerb'
+  p.developer('Eric Hodel', 'drbrain@segment7.net')
+end
+
+# vim: syntax=Ruby

data/bin/upnp_discover

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+
+require 'UPnP/SSDP'
+require 'UPnP/control'
+
+ssdp = UPnP::SSDP.new
+timeout = ARGV.shift
+timeout = if timeout then
+            begin
+              timeout = Integer timeout
+            rescue
+              abort <<-EOF
+Usage: #{$0} [timeout]
+
+Prints information about UPnP internet gateway devices
+              EOF
+            end
+          else
+            1
+          end
+
+ssdp.timeout = timeout
+
+devices = ssdp.search(:root).map do |resource|
+  UPnP::Control::Device.new resource.location
+end
+
+if devices.empty? then
+  puts 'No UPnP devices found'
+  exit
+end
+
+def print_device(device, indent = '  ')
+  out = []
+
+  out << "Friendly name: #{device.friendly_name}"
+  out << "Presentation URL: #{device.presentation_url}"
+  out << nil
+  out << "Unique device name: #{device.name}"
+  out << nil
+  out << "Manufacturer: #{device.manufacturer}"
+  out << "Manufacturer URL: #{device.manufacturer_url}"
+  out << nil
+  out << "Model name: #{device.model_name}"
+  out << "Model description: #{device.model_description}"
+  out << "Model URL: #{device.model_url}"
+  out << "UPC: #{device.upc}"
+  out << "Serial number: #{device.serial_number}"
+  out << nil
+
+  puts indent + out.join("\n#{indent}")
+end
+
+devices.each do |device|
+  type = device.type.sub "#{UPnP::DEVICE_SCHEMA_PREFIX}:", ''
+  puts "#{device.url}: #{type}"
+  print_device device
+
+  device.devices.each do |sub_device|
+    type = sub_device.type.sub "#{UPnP::DEVICE_SCHEMA_PREFIX}:", ''
+    puts "  Sub-device #{type}:"
+    print_device sub_device, '    '
+  end
+
+  device.services.each do |service|
+    type = service.type.sub("#{UPnP::DEVICE_SCHEMA_PREFIX}:", '')
+    puts "  Service: #{type}"
+    puts "    Id: #{service.id}"
+    puts "    Type: #{service.type}"
+    puts "    SCPD URL: #{service.scpd_url}"
+    puts "    Control URL: #{service.control_url}"
+    puts "    Event subscription URL: #{service.event_sub_url}"
+    puts
+    puts "    Actions:"
+    service.driver.methods(false).sort.each do |method|
+      puts "      #{method}"
+    end
+
+    puts
+  end
+end
+

data/bin/upnp_listen

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+
+require 'UPnP/SSDP'
+require 'UPnP/control'
+
+ssdp = UPnP::SSDP.new
+
+ssdp.discover do |notification|
+  schemas = Regexp.union UPnP::DEVICE_SCHEMA_PREFIX, UPnP::SERVICE_SCHEMA_PREFIX
+
+  type = notification.type.sub(/#{schemas}:/, '')
+
+  if notification.alive? then
+    puts "#{type} is alive"
+    puts "Description: #{notification.location}"
+    expiration = notification.expiration.strftime '%c'
+    puts "Valid until #{expiration}"
+  else
+    puts "#{type} says byebye"
+  end
+
+  puts "USN: #{notification.name}"
+
+  puts
+end
+

data/lib/UPnP.rb

@@ -0,0 +1,35 @@
+$KCODE = 'u'
+
+require 'rubygems'
+gem 'soap4r'
+
+##
+# An implementation of the Universal Plug and Play protocol.
+#
+# http://upnp.org/
+
+module UPnP
+
+  ##
+  # UPnP device schema prefix
+
+  DEVICE_SCHEMA_PREFIX = 'urn:schemas-upnp-org:device'
+
+  ##
+  # UPnP service schema prefix
+
+  SERVICE_SCHEMA_PREFIX = 'urn:schemas-upnp-org:service'
+
+  ##
+  # The version of UPnP you are using
+
+  VERSION = '1.0.0'
+
+  ##
+  # UPnP error base class
+
+  class Error < RuntimeError
+  end
+
+end
+

data/lib/UPnP/SSDP.rb

@@ -0,0 +1,495 @@
+require 'ipaddr'
+require 'socket'
+require 'thread'
+require 'time'
+require 'uri'
+
+require 'UPnP'
+require 'UPnP/control'
+
+##
+# Simple Service Discovery Protocol for the UPnP Device Architecture.
+#
+# Currently SSDP only handles the discovery portions of SSDP.
+#
+# To listen for SSDP notifications from UPnP devices:
+#
+#   ssdp = SSDP.new
+#   notifications = ssdp.listen
+#
+# To discover all devices and services:
+#
+#   ssdp = SSDP.new
+#   resources = ssdp.search
+#
+# After a device has been found you can create a Device object for it:
+#
+#   UPnP::Control::Device.create resource.location
+#
+# Based on code by Kazuhiro NISHIYAMA (zn@mbf.nifty.com)
+
+class UPnP::SSDP
+
+  ##
+  # SSDP Error class
+
+  class Error < UPnP::Error
+  end
+
+  ##
+  # Abstract class for SSDP advertisements
+
+  class Advertisement
+
+    ##
+    # Expiration time of this advertisement
+
+    def expiration
+      date + max_age
+    end
+
+    ##
+    # True if this advertisement has expired
+
+    def expired?
+      Time.now > expiration
+    end
+
+  end
+
+  ##
+  # Holds information about a NOTIFY message.  For an alive notification, all
+  # fields will be present.  For a byebye notification, location, max_age and
+  # server will be nil.
+
+  class Notification < Advertisement
+
+    ##
+    # Date the notification was received
+
+    attr_reader :date
+
+    ##
+    # Host the notification was sent from
+
+    attr_reader :host
+
+    ##
+    # Port the notification was sent from
+
+    attr_reader :port
+
+    ##
+    # Location of the advertised service or device
+
+    attr_reader :location
+
+    ##
+    # Maximum age the advertisement is valid for
+
+    attr_reader :max_age
+
+    ##
+    # Unique Service Name of the advertisement
+
+    attr_reader :name
+
+    ##
+    # Type of the advertised service or device
+
+    attr_reader :type
+
+    ##
+    # Server name and version of the advertised service or device
+
+    attr_reader :server
+
+    ##
+    # \Notification sub-type
+
+    attr_reader :sub_type
+
+    ##
+    # Parses a NOTIFY advertisement into its component pieces
+
+    def self.parse(advertisement)
+      advertisement = advertisement.gsub "\r", ''
+
+      advertisement =~ /^host:\s*(\S*)/i
+      host, port = $1.split ':'
+
+      advertisement =~ /^nt:\s*(\S*)/i
+      type = $1
+
+      advertisement =~ /^nts:\s*(\S*)/i
+      sub_type = $1
+
+      advertisement =~ /^usn:\s*(\S*)/i
+      name = $1
+
+      if sub_type == 'ssdp:alive' then
+        advertisement =~ /^cache-control:\s*max-age\s*=\s*(\d+)/i
+        max_age = Integer $1
+
+        advertisement =~ /^location:\s*(\S*)/i
+        location = URI.parse $1
+
+        advertisement =~ /^server:\s*(.*)/i
+        server = $1.strip
+      end
+
+      new Time.now, max_age, host, port, location, type, sub_type, server, name
+    end
+
+    ##
+    # Creates a \new Notification
+
+    def initialize(date, max_age, host, port, location, type, sub_type,
+                   server, name)
+      @date = date
+      @max_age = max_age
+      @host = host
+      @port = port
+      @location = location
+      @type = type
+      @sub_type = sub_type
+      @server = server
+      @name = name
+    end
+
+    ##
+    # Returns true if this is a notification for a resource being alive
+
+    def alive?
+      sub_type == 'ssdp:alive'
+    end
+
+    ##
+    # Returns true if this is a notification for a resource going away
+
+    def byebye?
+      sub_type == 'ssdp:byebye'
+    end
+
+    ##
+    # A friendlier inspect
+
+    def inspect
+      location = " #{@location}" if @location
+      "#<#{self.class}:0x#{object_id.to_s 16} #{@type} #{@sub_type}#{location}>"
+    end
+
+  end
+
+  ##
+  # Holds information about a M-SEARCH response
+
+  class Response < Advertisement
+
+    ##
+    # Date response was created or received
+
+    attr_reader :date
+
+    ##
+    # true if MAN header was understood
+
+    attr_reader :ext
+
+    ##
+    # URI where this device or service is described
+
+    attr_reader :location
+
+    ##
+    # Maximum age this advertisement is valid for
+
+    attr_reader :max_age
+
+    ##
+    # Unique Service Name
+
+    attr_reader :name
+
+    ##
+    # Server version string
+
+    attr_reader :server
+
+    ##
+    # Search target
+
+    attr_reader :target
+
+    ##
+    # Creates a new Response by parsing the text in +response+
+
+    def self.parse(response)
+      response =~ /^cache-control:\s*max-age\s*=\s*(\d+)/i
+      max_age = Integer $1
+
+      response =~ /^date:\s*(.*)/i
+      date = $1 ? Time.parse($1) : Time.now
+
+      ext = !!(response =~ /^ext:/i)
+
+      response =~ /^location:\s*(\S*)/i
+      location = URI.parse $1.strip
+
+      response =~ /^server:\s*(.*)/i
+      server = $1.strip
+
+      response =~ /^st:\s*(\S*)/i
+      target = $1.strip
+
+      response =~ /^usn:\s*(\S*)/i
+      name = $1.strip
+
+      new date, max_age, location, server, target, name, ext
+    end
+
+    ##
+    # Creates a new Response
+
+    def initialize(date, max_age, location, server, target, name, ext)
+      @date = date
+      @max_age = max_age
+      @location = location
+      @server = server
+      @target = target
+      @name = name
+      @ext = ext
+    end
+
+    ##
+    # A friendlier inspect
+
+    def inspect
+      "#<#{self.class}:0x#{object_id.to_s 16} #{target} #{location}>"
+    end
+
+  end
+
+  ##
+  # Default broadcast address
+
+  BROADCAST = '239.255.255.250'
+
+  ##
+  # Default port
+
+  PORT = 1900
+
+  ##
+  # Default timeout
+
+  TIMEOUT = 1
+
+  ##
+  # Default packet time to live (hops)
+
+  TTL = 4
+
+  ##
+  # Broadcast address to use when sending searches and listening for
+  # notifications
+
+  attr_accessor :broadcast
+
+  ##
+  # Listener accessor for tests.
+
+  attr_accessor :listener # :nodoc:
+
+  ##
+  # Port to use for SSDP searching and listening
+
+  attr_accessor :port
+
+  ##
+  # Queue accessor for tests
+
+  attr_accessor :queue # :nodoc:
+
+  ##
+  # Socket accessor for tests
+
+  attr_accessor :socket # :nodoc:
+
+  ##
+  # Time to wait for SSDP responses
+
+  attr_accessor :timeout
+
+  ##
+  # TTL for SSDP packets
+
+  attr_accessor :ttl
+
+  ##
+  # Creates a new SSDP object.  Use the accessors to override broadcast, port,
+  # timeout or ttl.
+
+  def initialize
+    @broadcast = BROADCAST
+    @port = PORT
+    @timeout = TIMEOUT
+    @ttl = TTL
+
+    @listener = nil
+    @queue = Queue.new
+  end
+
+  ##
+  # Discovers UPnP devices sending NOTIFY broadcasts.
+  #
+  # If given a block, yields each Notification as it is received and never
+  # returns.  Otherwise, discover waits for timeout seconds and returns all
+  # notifications received in that time.
+
+  def discover
+    membership = IPAddr.new(@broadcast).hton + IPAddr.new('0.0.0.0').hton
+
+    @socket ||= UDPSocket.new
+
+    @socket.setsockopt Socket::IPPROTO_IP, Socket::IP_TTL, [@ttl].pack('i')
+    @socket.setsockopt Socket::IPPROTO_IP, Socket::IP_ADD_MEMBERSHIP, membership
+
+    @socket.bind Socket::INADDR_ANY, @port
+
+    listen
+
+    if block_given? then
+      loop do
+        notification = @queue.pop
+
+        yield notification
+      end
+    else
+      sleep @timeout
+
+      notifications = []
+      notifications << @queue.pop until @queue.empty?
+      notifications
+    end
+  ensure
+    stop_listening
+    @socket.close if @socket and not @socket.closed?
+    @socket = nil
+  end
+
+  ##
+  # Listens for UDP packets from devices in a Thread and enqueues them for
+  # processing.  Requires a socket from search or discover.
+
+  def listen
+    return @listener if @listener and @listener.alive?
+
+    @listener = Thread.start do
+      loop do
+        response = @socket.recvfrom(1024).first
+
+        begin
+          @queue << parse(response)
+        rescue
+          puts $!.message
+          puts $!.backtrace
+        end
+      end
+    end
+  end
+
+  ##
+  # Returns a Notification or Response created from +response+.
+
+  def parse(response)
+    case response
+    when /\ANOTIFY/ then
+      Notification.parse response
+    when /\AHTTP/ then
+      Response.parse response
+    else
+      raise Error, "Unknown response #{response[/\A.*$/]}"
+    end
+  end
+
+  ##
+  # Broadcasts M-SEARCH requests looking for +targets+.  Waits timeout seconds
+  # for responses then returns the collected responses.
+  #
+  # Supply no arguments to search for all devices and services.
+  #
+  # Supply <tt>:root</tt> to search for root devices only.
+  #
+  # Supply <tt>[:device, 'device_type:version']</tt> to search for a specific
+  # device type.
+  #
+  # Supply <tt>[:service, 'service_type:version']</tt> to search for a
+  # specific service type.
+  #
+  # Supply <tt>"uuid:..."</tt> to search for a UUID.
+  #
+  # Supply <tt>"urn:..."</tt> to search for a URN.
+
+  def search(*targets)
+    @socket ||= UDPSocket.new
+
+    @socket.setsockopt Socket::IPPROTO_IP, Socket::IP_TTL, [@ttl].pack('i')
+
+    if targets.empty? then
+      send_search 'ssdp:all'
+    else
+      targets.each do |target|
+        if target == :root then
+          send_search 'upnp:rootdevice'
+        elsif Array === target and target.first == :device then
+          target = [UPnP::DEVICE_SCHEMA_PREFIX, target.last]
+          send_search target.join(':')
+        elsif Array === target and target.first == :service then
+          target = [UPnP::SERVICE_SCHEMA_PREFIX, target.last]
+          send_search target.join(':')
+        elsif String === target and target =~ /\A(urn|uuid|ssdp):/ then
+          send_search target
+        end
+      end
+    end
+
+    listen
+    sleep @timeout
+
+    responses = []
+    responses << @queue.pop until @queue.empty?
+    responses
+  ensure
+    stop_listening
+    @socket.close if @socket and not @socket.closed?
+    @socket = nil
+  end
+
+  ##
+  # Builds and sends an M-SEARCH request looking for +search_target+.
+
+  def send_search(search_target)
+    http_request = <<HTTP_REQUEST
+M-SEARCH * HTTP/1.1\r
+HOST: #{@broadcast}:#{@port}\r
+MAN: "ssdp:discover"\r
+MX: #{@timeout}\r
+ST: #{search_target}\r
+\r
+HTTP_REQUEST
+
+    @socket.send http_request, 0, @broadcast, @port
+  end
+
+  ##
+  # Stops and clears the listen thread.
+
+  def stop_listening
+    @listener.kill if @listener
+    @queue = Queue.new
+    @listener = nil
+  end
+
+end
+