UPnP 1.0.0 → 1.1.0

data/lib/UPnP/UUID.rb

@@ -0,0 +1,187 @@
+# Original code copyright (c) 2005,2007 Assaf Arkin
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'fileutils'
+require 'thread'
+require 'tmpdir'
+require 'UPnP'
+
+##
+# This UUID class is here to make Assaf Arkin's uuid gem not write to $stdout.
+# Used under MIT license (see source code).
+#
+# To generate a UUID:
+#
+#   UUID.setup
+#   uuid = UUID.new
+#   uuid.generate
+
+class UPnP::UUID
+
+  ##
+  # File holding the NIC MAC address
+
+  NIC_FILE = '~/.UPnP/uuid_mac_address'
+
+  ##
+  # Clock multiplier. Converts Time (resolution: seconds) to UUID clock
+  # (resolution: 10ns)
+
+  CLOCK_MULTIPLIER = 10000000
+
+  ##
+  # Clock gap is the number of ticks (resolution: 10ns) between two Ruby Time
+  # ticks.
+
+  CLOCK_GAPS = 100000
+
+  ##
+  # Version number stamped into the UUID to identify it as time-based.
+
+  VERSION_CLOCK = 0x0100
+
+  ##
+  # Formats supported by the UUID generator.
+  #
+  # <tt>:default</tt>:: Produces 36 characters, including hyphens separating
+  #                     the UUID value parts
+  # <tt>:compact</tt>:: Produces a 32 digits (hexadecimal) value with no
+  #                     hyphens
+  # <tt>:urn</tt>:: Adds the prefix <tt>urn:uuid:</tt> to the
+  #                 <tt>:default</tt> format
+
+  FORMATS = {
+    :compact => '%08x%04x%04x%04x%012x',
+    :default => '%08x-%04x-%04x-%04x-%012x',
+    :urn     => 'urn:uuid:%08x-%04x-%04x-%04x-%012x',
+  }
+
+  @uuid = nil
+
+  ##
+  # Sets up the UUID class generates a UUID in the default format.
+
+  def self.generate(nic_file = NIC_FILE)
+    return @uuid.generate if @uuid
+    setup nic_file
+    @uuid = new
+    @uuid.generate
+  end
+
+  ##
+  # Discovers the NIC MAC address and saves it to +nic_file+.  Works for UNIX
+  # (ifconfig) and Windows (ipconfig).
+
+  def self.setup(nic_file = NIC_FILE)
+    nic_file = File.expand_path nic_file
+
+    return if File.exist? nic_file
+
+    FileUtils.mkdir_p File.dirname(nic_file)
+
+    # Run ifconfig for UNIX, or ipconfig for Windows.
+    config = ''
+    Dir.chdir Dir.tmpdir do
+      config << `ifconfig 2>/dev/null`
+      config << `ipconfig /all 2>NUL`
+    end
+
+    addresses = config.scan(/[^:\-](?:[\da-z][\da-z][:\-]){5}[\da-z][\da-z][^:\-]/i)
+    addresses = addresses.map { |addr| addr[1..-2] }
+
+    raise Error, 'MAC address not found via ifconfig or ipconfig' if
+      addresses.empty?
+
+    open nic_file, 'w' do |io| io.write addresses.first end
+  end
+
+  ##
+  # Creates a new UUID generator using the NIC stored in NIC_FILE.
+
+  def initialize(nic_file = NIC_FILE)
+    if File.exist? nic_file then
+      address = File.read nic_file
+
+      raise Error, "invalid MAC address #{address}" unless
+        address =~ /([\da-f]{2}[:\-]){5}[\da-f]{2}/i
+      @address = address.scan(/[0-9a-fA-F]{2}/).join.hex & 0x7FFFFFFFFFFF
+    else
+      @address = rand(0x800000000000) | 0xF00000000000
+    end
+
+    @drift = 0
+    @last_clock = (Time.new.to_f * CLOCK_MULTIPLIER).to_i
+    @mutex = Mutex.new
+    @sequence = rand 0x10000
+  end
+
+  ##
+  # Generates a new UUID string using +format+.  See FORMATS for a list of
+  # supported formats.
+
+  def generate(format = :default)
+    template = FORMATS[format]
+
+    raise ArgumentError, "unknown UUID format #{format.inspect}" if
+      template.nil?
+
+    # The clock must be monotonically increasing. The clock resolution is at
+    # best 100 ns (UUID spec), but practically may be lower (on my setup,
+    # around 1ms). If this method is called too fast, we don't have a
+    # monotonically increasing clock, so the solution is to just wait.
+    #
+    # It is possible for the clock to be adjusted backwards, in which case we
+    # would end up blocking for a long time. When backward clock is detected,
+    # we prevent duplicates by asking for a new sequence number and continue
+    # with the new clock.
+
+    clock = @mutex.synchronize do
+      clock = (Time.new.to_f * CLOCK_MULTIPLIER).to_i & 0xFFFFFFFFFFFFFFF0
+
+      if clock > @last_clock then
+        @drift = 0
+        @last_clock = clock
+      elsif clock == @last_clock then
+        drift = @drift += 1
+
+        if drift < 10000
+          @last_clock += 1
+        else
+          Thread.pass
+          nil
+        end
+      else
+        @sequence = rand 0x10000
+        @last_clock = clock
+      end
+    end while not clock
+
+    template % [
+      clock & 0xFFFFFFFF,
+      (clock >> 32) & 0xFFFF,
+      ((clock >> 48) & 0xFFFF | VERSION_CLOCK),
+      @sequence & 0xFFFF,
+      @address & 0xFFFFFFFFFFFF
+    ]
+  end
+
+end
+

data/lib/UPnP/control/service.rb

@@ -217,7 +217,9 @@ class UPnP::Control::Service
 
   def self.create(description, url)
     type = description.elements['serviceType'].text.strip
-    klass_name = type.sub(/#{UPnP::SERVICE_SCHEMA_PREFIX}:([^:]+):.*/, '\1')
+
+    # HACK need vendor namespaces
+    klass_name = type.sub(/urn:[^:]+:service:([^:]+):.*/, '\1')
 
     begin
       klass = const_get klass_name
@@ -386,6 +388,7 @@ class UPnP::Control::Service
     range = [minimum, maximum, step]
 
     range.map do |value|
+      value = value.text
       value =~ /\./ ? Float(value) : Integer(value)
     end
   end

data/lib/UPnP/device.rb

@@ -0,0 +1,692 @@
+require 'UPnP'
+require 'UPnP/SSDP'
+require 'UPnP/UUID'
+require 'UPnP/root_server'
+require 'UPnP/service'
+require 'builder'
+require 'fileutils'
+
+##
+# A device contains sub devices, services and holds information about the
+# services provided.  If you use ::create, UPnP will maintain device UUIDs
+# across startups.
+#
+# = Creating a UPnP::Device class
+#
+# A concrete UPnP device looks like this:
+#
+#   require 'UPnP/device'
+#   require 'UPnP/service/content_directory'
+#   require 'UPnP/service/connection_manager'
+#   
+#   class UPnP::Device::MediaServer < UPnP::Device
+#     VERSION = '1.0'
+#   
+#     add_service_id UPnP::Service::ContentDirectory, 'ContentDirectory'
+#     add_service_id UPnP::Service::ConnectionManager, 'ConnectorManager'
+#   end
+#
+# Require the sub-services and sub-devices this device requires.  For a
+# MediaServer, only a ContentDirectory and ConnectionManager service is
+# required.
+#
+# Subclass UPnP::Device in the UPnP::Device namespace.  UPnP::Device looks in
+# its own namespace for various information when instantiating the device.
+#
+# Add a VERSION constant for your device implementation.  This will be
+# reported in device advertisements.
+#
+# Add the service ids defined in the device specification document.  Not every
+# service's type matches up to its service id.
+#
+# = Instantiating a UPnP::Device
+#
+# A device instantiation looks like this:
+#
+#   name = Socket.gethostname.split('.', 2).first
+#   
+#   device = UPnP::Device.create 'MediaServer', name do |ms|
+#     ms.manufacturer = 'Eric Hodel'
+#     ms.model_name = 'Media Server'
+#   
+#     ms.add_service 'ContentDirectory'
+#     ms.add_service 'ConnectionManager'
+#   end
+#
+# The first argument to ::create is the device type.  UPnP looks in the
+# UPnP::Device namespace for a constant matching this name.  The second is the
+# friendly name of the device.  (A hostname-based name seems sane enough for
+# this example.)
+#
+# Various UPnP device settings can be given next.  The manufacturer and model
+# name are required by the UPnP specification.  The remainder are attributes
+# you can see below.
+#
+# add_service adds a service of the given type to the device.  UPnP looks in
+# the UPnP::Service namespace for a constant matching this name.
+#
+# #add_device can be used to add a sub-device.  Like ::create, it takes a type
+# and friendly name, and yield a block that you must set the manufacturer and
+# model name in, in addition to any required sub-devices and sub-services.
+#
+# = Running a UPnP Device
+#
+# After instantiating a device it will advertise itself to the network when
+# you call #run.
+#
+# = Creating a UPnP device executable
+#
+# All the methods you need to create a UPnP device executable are built-in,
+# you only need to override option_parser and ::run in your UPnP::Device
+# subclass.  See the documentation below for details.
+#
+# When you're done, create an executable file, require your device file, and
+# call ::run on your class:
+#
+#   #!/usr/bin/env ruby
+#   
+#   require 'rubygems'
+#   require 'UPnP/device/my_device'
+#   
+#   UPnP::Device::MyDevice.run
+#
+# Mark it as executable, and you are good to go!
+
+class UPnP::Device
+
+  ##
+  # Base device error class
+
+  class Error < UPnP::Error
+  end
+
+  ##
+  # Raised when device validation fails
+
+  class ValidationError < Error
+  end
+
+  ##
+  # Maps services for a device to their service ids
+
+  SERVICE_IDS = Hash.new { |h, device| h[device] = {} }
+
+  ##
+  # UPnP 1.0 device schema
+
+  SCHEMA_URN = 'urn:schemas-upnp-org:device-1-0'
+
+  ##
+  # Short device description for the end user
+
+  attr_accessor :friendly_name
+
+  ##
+  # Manufacturer's name
+
+  attr_accessor :manufacturer
+
+  ##
+  # Manufacturer's web site
+
+  attr_accessor :manufacturer_url
+
+  ##
+  # Long model description for the end user
+
+  attr_accessor :model_description
+
+  ##
+  # Model name
+
+  attr_accessor :model_name
+
+  ##
+  # Model number
+
+  attr_accessor :model_number
+
+  ##
+  # Web site for model
+
+  attr_accessor :model_url
+
+  ##
+  # Unique Device Name (UDN), a universally unique identifier for the device
+  # whether root or embedded.
+
+  attr_accessor :name
+
+  ##
+  # This device's parent device, or nil if it is the root.
+
+  attr_reader :parent
+
+  ##
+  # Serial number
+
+  attr_accessor :serial_number
+
+  ##
+  # Devices that are immediate children of this device
+
+  attr_accessor :sub_devices
+
+  ##
+  # Services that are immediate children of this device
+
+  attr_accessor :sub_services
+
+  ##
+  # Type of UPnP device.  Use type_urn for the full URN
+
+  attr_reader :type
+
+  ##
+  # Universal Product Code
+
+  attr_accessor :upc
+
+  @option_parser = nil
+  @options = nil
+
+  def self.add_service_id(service, id)
+    SERVICE_IDS[self][service] = id
+  end
+
+  ##
+  # Loads a device of type +type+ and named +friendly_name+, or creates a new
+  # device from +block+ and dumps it.
+  #
+  # If a dump exists for the same device type and friendly_name the dump is
+  # loaded and used as defaults.  This preserves the device name (UUID) across
+  # device restarts.
+
+  def self.create(type, friendly_name, &block)
+    klass = const_get type
+
+    device_definition = File.join '~', '.UPnP', type, friendly_name
+    device_definition = File.expand_path device_definition
+
+    device = nil
+
+    if File.exist? device_definition then
+      open device_definition, 'rb' do |io|
+        device = Marshal.load io.read
+      end
+
+      yield device if block_given?
+    else
+      device = klass.new type, friendly_name, &block
+    end
+
+    device.dump
+    device
+  rescue NameError => e
+    raise unless e.message =~ /UPnP::Service::#{type}/
+    raise Error, "unknown device type #{type}"
+  end
+
+  ##
+  # True when in debug mode
+
+  def self.debug?
+    @debug ||= false
+  end
+
+  ##
+  # Set debug mode to +value+
+
+  def self.debug=(value)
+    @debug = value
+  end
+
+  ##
+  # Creates an instance of the UPnP::Device subclass named +type+ if it is in
+  # the UPnP::Device namespace.
+
+  def self.new(type, *args)
+    if UPnP::Device == self then
+      klass = begin
+                const_get type
+              rescue NameError
+                self
+              end
+
+      klass.new(type, *args)
+    else
+      super
+    end
+  end
+
+  ##
+  # Creates a new OptionParser and yields the option parser and an options
+  # hash for adding a banner or setting device-specific command line
+  # arguments.
+  #
+  # Example:
+  #
+  #   def self.option_parser
+  #     super do |option_parser, options|
+  #       options[:name] = Socket.gethostname.split('.', 2).first
+  #   
+  #       option_parser.banner = <<-EOF
+  #   Usage: #{option_parser.program_name} [options]
+  #   
+  #   Starts a thingy with the stuff...
+  #       EOF
+  #   
+  #       option_parser.on '-n', '--name=NAME', 'Set the name' do |value|
+  #         options[:name] = value
+  #       end
+  #     end
+  #   end
+  #
+  # option_parser automatically provides debug, help and version options.  See
+  # also OptionParser in ri for more information on working with OptionParser.
+
+  def self.option_parser
+    require 'optparse'
+
+    @options = {}
+
+    @option_parser = OptionParser.new do |option_parser|
+      option_parser.version = if const_defined? :VERSION then
+                                self::VERSION
+                              else
+                                UPnP::VERSION
+                              end
+
+      option_parser.summary_indent = ' ' * 4
+
+      yield option_parser, @options
+
+      option_parser.program_name = File.basename $0 unless
+        option_parser.program_name
+
+      unless option_parser.banner then
+        option_parser.banner = "Usage: #{option_parser.program_name} [options]"
+      end
+
+      option_parser.separator ''
+
+      option_parser.on('--[no-]debug', 'Provide extra logging') do |value|
+        @debug = value
+      end
+    end
+  end
+
+  ##
+  # Processes +argv+, but must be overridden in a subclass to
+  # create and run the device.
+  #
+  # Override this in a subclass. The overriden run should super, then #create
+  # a device using @options as parsed by option_parser, then call #run on the
+  # created device.
+  #
+  # Example:
+  #
+  #  def self.run(argv = ARGV)
+  #    super
+  #  
+  #    device = create 'MyDevice' do |md|
+  #      md.manufacturer = '...'
+  #      # device-specific setup
+  #    end
+  #  
+  #    device.run
+  #  end
+  #
+  # run takes care of invalid arguments and options for you by printing out
+  # the help followed by the invalid argument.
+
+  def self.run(argv = ARGV)
+    option_parser.parse argv
+  rescue OptionParser::InvalidOption, OptionParser::InvalidArgument,
+         OptionParser::NeedlessArgument => e
+    puts option_parser
+    puts
+    puts e
+
+    exit 1
+  end
+
+  ##
+  # Creates a new device of +type+ using +friendly_name+ with a new name
+  # (UUID).  Use #dump and ::create to preserve device names.
+
+  def initialize(type, friendly_name, parent_device = nil)
+    @type = type
+    @friendly_name = friendly_name
+
+    @manufacturer ||= nil
+    @manufacturer_url ||= nil
+
+    @model_description ||= nil
+    @model_name ||= nil
+    @model_number ||= nil
+    @model_url ||= nil
+
+    @serial_number ||= nil
+    @upc ||= nil
+
+    @sub_devices ||= []
+    @sub_services ||= []
+    @parent ||= parent_device
+
+    yield self if block_given?
+
+    @name ||= "uuid:#{UPnP::UUID.generate}"
+
+    @ssdp = nil
+  end
+
+  ##
+  # A device is equal to another device if it has the same name
+
+  def ==(other)
+    UPnP::Device === other and @name == other.name
+  end
+
+  ##
+  # Adds a sub-device of +type+ with +friendly_name+.  Devices must have
+  # unique types and friendly names.  A sub-device will not be created if it
+  # already exists, but the block will be called with the existing sub-device.
+
+  def add_device(type, friendly_name = type, &block)
+    sub_device = @sub_devices.find do |d|
+      d.type == type and d.friendly_name == friendly_name
+    end
+
+    if sub_device then
+      yield sub_device if block_given?
+      return sub_device
+    end
+
+    sub_device = UPnP::Device.new(type, friendly_name, self, &block)
+    @sub_devices << sub_device
+    sub_device
+  end
+
+  ##
+  # Adds a UPnP::Service of +type+.  +block+ is passed to the created service
+  # for service-specific setup.
+
+  def add_service(type, &block)
+    sub_service = @sub_services.find { |s| s.type == type }
+    block.call sub_service if sub_service and block
+    return sub_service if sub_service
+
+    sub_service = UPnP::Service.create(self, type, &block)
+    @sub_services << sub_service
+    sub_service
+  end
+
+  ##
+  # Advertises this device, its sub-devices and services.  Always advertises
+  # from the root device.
+
+  def advertise
+    addrinfo = Socket.getaddrinfo Socket.gethostname, 0, Socket::AF_INET,
+                                  Socket::SOCK_STREAM
+    @hosts = addrinfo.map { |type, port, host, ip,| ip }.uniq
+
+    @advertise_thread = Thread.start do
+      Thread.abort_on_exception = true
+
+      ssdp.advertise root_device, @server[:Port], @hosts
+    end
+  end
+
+  ##
+  # Returns an XML document describing the root device
+
+  def description
+    validate
+
+    description = []
+
+    xml = Builder::XmlMarkup.new :indent => 2, :target => description
+    xml.instruct!
+
+    xml.root :xmlns => SCHEMA_URN do
+      xml.specVersion do
+        xml.major 1
+        xml.minor 0
+      end
+
+      root_device.device_description xml
+    end
+
+    description.join
+  end
+
+  ##
+  # Adds a description for this device to +xml+
+
+  def device_description(xml)
+    validate
+
+    xml.device do
+      xml.deviceType       type_urn
+      xml.UDN              @name
+
+      xml.friendlyName     @friendly_name
+
+      xml.manufacturer     @manufacturer
+      xml.manufacturerURL  @manufacturer_url  if @manufacturer_url
+
+      xml.modelDescription @model_description if @model_description
+      xml.modelName        @model_name
+      xml.modelNumber      @model_number      if @model_number
+      xml.modelURL         @model_url         if @model_url
+
+      xml.serialNumber     @serial_number     if @serial_number
+
+      xml.UPC              @upc               if @upc
+
+      unless @sub_services.empty? then
+        xml.serviceList do
+          @sub_services.each do |service|
+            service.description(xml)
+          end
+        end
+      end
+
+      unless @sub_devices.empty? then
+        xml.deviceList do
+          @sub_devices.each do |device|
+            device.device_description(xml)
+          end
+        end
+      end
+    end
+  end
+
+  ##
+  # This device and all its sub-devices
+
+  def devices
+    [self] + @sub_devices.map do |device|
+      device.devices
+    end.flatten
+  end
+
+  ##
+  # Writes this device description into ~/.UPnP so an identically named
+  # version can be created on the next load.
+
+  def dump
+    device_definition = File.join '~', '.UPnP', @type, @friendly_name
+    device_definition = File.expand_path device_definition
+
+    FileUtils.mkdir_p File.dirname(device_definition)
+
+    open device_definition, 'wb' do |io|
+      Marshal.dump self, io
+    end
+  end
+
+  ##
+  # Custom Marshal method that only dumps device-specific data.
+
+  def marshal_dump
+    [
+      @type,
+      @friendly_name,
+      @sub_devices,
+      @sub_services,
+      @parent,
+      @name,
+      @manufacturer,
+      @manufacturer_url,
+      @model_description,
+      @model_name,
+      @model_number,
+      @model_url,
+      @serial_number,
+      @upc,
+    ]
+  end
+
+  ##
+  # Custom Marshal method that only loads device-specific data.
+
+  def marshal_load(data)
+    @type              = data.shift
+    @friendly_name     = data.shift
+    @sub_devices       = data.shift
+    @sub_services      = data.shift
+    @parent            = data.shift
+    @name              = data.shift
+    @manufacturer      = data.shift
+    @manufacturer_url  = data.shift
+    @model_description = data.shift
+    @model_name        = data.shift
+    @model_number      = data.shift
+    @model_url         = data.shift
+    @serial_number     = data.shift
+    @upc               = data.shift
+  end
+
+  ##
+  # This device's root device
+
+  def root_device
+    device = self
+    device = device.parent until device.parent.nil?
+    device
+  end
+
+  ##
+  # Starts a root server for the device and advertises it via SSDP.  INT and
+  # TERM signal handlers are automatically added, and exit when invoked.  This
+  # method won't return until the server is shutdown.
+
+  def run
+    setup_server
+    advertise
+
+    puts "listening on port #{@server[:Port]}"
+
+    trap 'INT'  do shutdown; exit end
+    trap 'TERM' do shutdown; exit end
+
+    @server.start
+  end
+
+  ##
+  # Retrieves a serviceId for +service+ from the concrete device's service id
+  # list
+
+  def service_id(service)
+    service_id = service_ids[service.class]
+
+    raise Error, "unknown serviceId for #{service.class}" unless service_id
+
+    service_id
+  end
+
+  ##
+  # Retrieves the concrete device's service id list.  Requires a SERVICE_IDS
+  # constant in the concrete class.
+
+  def service_ids
+    SERVICE_IDS[self.class]
+  end
+
+  ##
+  # All service and sub-services of this device
+
+  def services
+    services = @sub_services.dup
+    services.push(*@sub_devices.map { |d| d.services })
+    services.flatten
+  end
+
+  ##
+  # Shut down this device
+
+  def shutdown
+    @advertise_thread.kill if @advertise_thread
+
+    ssdp.byebye self, @hosts
+
+    @server.shutdown
+  end
+
+  ##
+  # Creates a root server and attaches this device's services to it.
+
+  def setup_server
+    @server = UPnP::RootServer.new self
+
+    services.each do |service|
+      @server.mount_service service
+    end
+
+    @server
+  end
+
+  ##
+  # UPnP::SSDP accessor
+
+  def ssdp
+    return @ssdp if @ssdp
+
+    @ssdp = UPnP::SSDP.new
+    @ssdp.log = @server[:Logger]
+
+    @ssdp
+  end
+
+  ##
+  # URN of this device's type
+
+  def type_urn
+    "#{UPnP::DEVICE_SCHEMA_PREFIX}:#{@type}:1"
+  end
+
+  ##
+  # Raises a ValidationError if any of the required fields are nil
+
+  def validate
+    raise ValidationError, 'friendly_name missing' if @friendly_name.nil?
+    raise ValidationError, 'manufacturer missing' if @manufacturer.nil?
+    raise ValidationError, 'model_name missing' if @model_name.nil?
+  end
+
+  ##
+  # The version of this device, or the UPnP version if the device did not
+  # define it
+
+  def version
+    if self.class.const_defined? :VERSION then
+      self.class::VERSION
+    else
+      UPnP::VERSION
+    end
+  end
+
+end
+