druzy-upnp 1.0.0

data/lib/druzy/upnp/ssdp/listener.rb

@@ -0,0 +1,36 @@
+require_relative 'multicast_connection'
+
+
+class Druzy::Upnp::SSDP::Listener < Druzy::Upnp::SSDP::MulticastConnection
+
+  # @return [EventMachine::Channel] Provides subscribers with notifications
+  #   from devices that have come online (sent +ssdp:alive+ notifications).
+  attr_reader :alive_notifications
+
+  # @return [EventMachine::Channel] Provides subscribers with notifications
+  #   from devices that have gone offline (sent +ssd:byebye+ notifications).
+  attr_reader :byebye_notifications
+
+  # This is the callback called by EventMachine when it receives data on the
+  # socket that's been opened for this connection.  In this case, the method
+  # parses the SSDP notifications into Hashes and adds them to the
+  # appropriate EventMachine::Channel (provided as accessor methods).  This
+  # effectively means that in each Channel, you get a Hash that represents
+  # the headers for each notification that comes in on the socket.
+  #
+  # @param [String] response The data received on this connection's socket.
+  def receive_data(response)
+    ip, port = peer_info
+    parsed_response = parse(response)
+
+    return unless parsed_response.has_key? :nts
+
+    if parsed_response[:nts] == 'ssdp:alive'
+      @alive_notifications << parsed_response
+    elsif parsed_response[:nts] == 'ssdp:byebye'
+      @byebye_notifications << parsed_response
+    else
+      raise "Unknown NTS value: #{parsed_response[:nts]}"
+    end
+  end
+end

data/lib/druzy/upnp/ssdp/multicast_connection.rb

@@ -0,0 +1,109 @@
+require 'core_ext/socket_patch'
+require_relative 'network_constants'
+require_relative 'error'
+require 'ipaddr'
+require 'socket'
+require 'eventmachine'
+require 'em-synchrony'
+
+module Druzy
+  module Upnp
+    class SSDP
+      class MulticastConnection < EventMachine::Connection
+        include Druzy::Upnp::SSDP::NetworkConstants
+  
+        # @param [Fixnum] ttl The TTL value to use when opening the UDP socket
+        #   required for SSDP actions.
+        def initialize(ttl=TTL)
+          @ttl = ttl
+  
+          @discovery_responses = EM::Channel.new
+          @alive_notifications = EM::Channel.new
+          @byebye_notifications = EM::Channel.new
+  
+          setup_multicast_socket
+        end
+  
+        # Gets the IP and port from the peer that just sent data.
+        #
+        # @return [Array<String,Fixnum>] The IP and port.
+        def peer_info
+          peer_bytes = get_peername[2, 6].unpack('nC4')
+          port = peer_bytes.first.to_i
+          ip = peer_bytes[1, 4].join('.')
+  
+          [ip, port]
+        end
+  
+        # Converts the headers to a set of key-value pairs.
+        #
+        # @param [String] data The data to convert.
+        # @return [Hash] The converted data.  Returns an empty Hash if it didn't
+        #   know how to parse.
+        def parse(data)
+          new_data = {}
+  
+          unless data =~ /\n/
+            return new_data
+          end
+  
+          data.each_line do |line|
+            line =~ /(\S+):(.*)/
+  
+            unless $1.nil?
+              key = $1
+              value = $2
+              key = key.gsub('-', '_').downcase.to_sym
+              new_data[key] = value.strip
+            end
+          end
+  
+          new_data
+        end
+  
+        # Sets Socket options to allow for multicasting.  If ENV["RUBY_UPNP_ENV"] is
+        # equal to "testing", then it doesn't turn off multicast looping.
+        def setup_multicast_socket
+          set_membership(IPAddr.new(MULTICAST_IP).hton +
+            IPAddr.new('0.0.0.0').hton)
+          set_multicast_ttl(@ttl)
+          set_ttl(@ttl)
+  
+          unless ENV['RUBY_UPNP_ENV'] == 'testing'
+            switch_multicast_loop :off
+          end
+        end
+  
+        # @param [String] membership The network byte ordered String that represents
+        #   the IP(s) that should join the membership group.
+        def set_membership(membership)
+          set_sock_opt(Socket::IPPROTO_IP, Socket::IP_ADD_MEMBERSHIP, membership)
+        end
+  
+        # @param [Fixnum] ttl TTL to set IP_MULTICAST_TTL to.
+        def set_multicast_ttl(ttl)
+          set_sock_opt(Socket::IPPROTO_IP, Socket::IP_MULTICAST_TTL,
+            [ttl].pack('i'))
+        end
+  
+        # @param [Fixnum] ttl TTL to set IP_TTL to.
+        def set_ttl(ttl)
+          set_sock_opt(Socket::IPPROTO_IP, Socket::IP_TTL, [ttl].pack('i'))
+        end
+  
+        # @param [Symbol] on_off Turn on/off multicast looping.  Supply :on or :off.
+        def switch_multicast_loop(on_off)
+          hex_value = case on_off
+          when :on then "\001"
+          when "\001" then "\001"
+          when :off then "\000"
+          when "\000" then "\000"
+          else raise SSDP::Error, "Can't switch IP_MULTICAST_LOOP to '#{on_off}'"
+          end
+  
+          set_sock_opt(Socket::IPPROTO_IP, Socket::IP_MULTICAST_LOOP, hex_value)
+        end
+      end
+    end
+  end
+end

data/lib/druzy/upnp/ssdp/network_constants.rb

@@ -0,0 +1,19 @@
+module Druzy
+  module Upnp
+    class SSDP
+      module NetworkConstants
+  
+        BROADCAST_IP = '255.255.255.255'
+  
+        # Default multicast IP address
+        MULTICAST_IP = '239.255.255.250'
+  
+        # Default multicast port
+        MULTICAST_PORT = 1900
+  
+        # Default TTL
+        TTL = 4
+      end
+    end
+  end
+end

data/lib/druzy/upnp/ssdp/notifier.rb

@@ -0,0 +1,39 @@
+require_relative 'multicast_connection'
+
+
+class Druzy::Upnp::SSDP::Notifier < Druzy::Upnp::SSDP::MulticastConnection
+
+  def initialize(nt, usn, ddf_url, valid_for_duration)
+    @os = RbConfig::CONFIG['host_vendor'].capitalize + '/' +
+      RbConfig::CONFIG['host_os']
+    @upnp_version = '1.0'
+    @notification = notification(nt, usn, ddf_url, valid_for_duration)
+  end
+
+  def post_init
+    if send_datagram(@notification, MULTICAST_IP, MULTICAST_PORT) > 0
+
+    end
+  end
+
+  # @param [String] nt "Notification Type"; a potential search target.  Used in
+  #   +NT+ header.
+  # @param [String] usn "Unique Service Name"; a composite identifier for the
+  #   advertisement.  Used in +USN+ header.
+  # @param [String] ddf_url Device Description File URL for the root device.
+  # @param [Fixnum] valid_for_duration Duration in seconds for which the
+  #   advertisement is valid.  Used in +CACHE-CONTROL+ header.
+  def notification(nt, usn, ddf_url, valid_for_duration)
+    <<-NOTIFICATION
+NOTIFY * HTTP/1.1\r
+HOST: #{MULTICAST_IP}:#{MULTICAST_PORT}\r
+CACHE-CONTROL: max-age=#{valid_for_duration}\r
+LOCATION: #{ddf_url}\r
+NT: #{nt}\r
+NTS: ssdp:alive\r
+SERVER: #{@os} UPnP/#{@upnp_version} Playful/#{Playful::VERSION}\r
+USN: #{usn}\r
+\r
+    NOTIFICATION
+  end
+end

data/lib/druzy/upnp/ssdp/searcher.rb

@@ -0,0 +1,85 @@
+require_relative 'multicast_connection'
+
+module Druzy
+  module Upnp
+  
+    # A subclass of an EventMachine::Connection, this handles doing M-SEARCHes.
+    #
+    # Search types:
+    #   ssdp:all
+    #   upnp:rootdevice
+    #   uuid:[device-uuid]
+    #   urn:schemas-upnp-org:device:[deviceType-version]
+    #   urn:schemas-upnp-org:service:[serviceType-version]
+    #   urn:[custom-schema]:device:[deviceType-version]
+    #   urn:[custom-schema]:service:[serviceType-version]
+    class SSDP::Searcher < SSDP::MulticastConnection
+  
+      DEFAULT_RESPONSE_WAIT_TIME = 5
+      DEFAULT_M_SEARCH_COUNT = 2
+  
+      # @return [EventMachine::Channel] Provides subscribers with responses from
+      #   their search request.
+      attr_reader :discovery_responses
+  
+      # @param [String] search_target
+      # @param [Hash] options
+      # @option options [Fixnum] response_wait_time
+      # @option options [Fixnum] ttl
+      # @option options [Fixnum] m_search_count The number of times to send the
+      #   M-SEARCH.  UPnP 1.0 suggests to send the request more than once.
+      def initialize(search_target, options = {})
+        options[:ttl] ||= TTL
+        options[:response_wait_time] ||= DEFAULT_RESPONSE_WAIT_TIME
+        @m_search_count = options[:m_search_count] ||= DEFAULT_M_SEARCH_COUNT
+  
+        @search = m_search(search_target, options[:response_wait_time])
+  
+        super options[:ttl]
+      end
+  
+      # This is the callback called by EventMachine when it receives data on the
+      # socket that's been opened for this connection.  In this case, the method
+      # parses the SSDP responses/notifications into Hashes and adds them to the
+      # appropriate EventMachine::Channel (provided as accessor methods).  This
+      # effectively means that in each Channel, you get a Hash that represents
+      # the headers for each response/notification that comes in on the socket.
+      #
+      # @param [String] response The data received on this connection's socket.
+      def receive_data(response)
+        ip, port = peer_info
+        parsed_response = parse(response)
+  
+        return if parsed_response.has_key? :nts
+        return if parsed_response[:man] &&
+          parsed_response[:man] =~ /ssdp:discover/
+  
+        @discovery_responses << parsed_response
+      end
+  
+      # Sends the M-SEARCH that was built during init.  Logs what was sent if the
+      # send was successful.
+      def post_init
+        @m_search_count.times do
+          send_datagram(@search, MULTICAST_IP, MULTICAST_PORT)
+          
+        end
+      end
+  
+      # Builds the M-SEARCH request string.
+      #
+      # @param [String] search_target
+      # @param [Fixnum] response_wait_time
+      def m_search(search_target, response_wait_time)
+        <<-MSEARCH
+M-SEARCH * HTTP/1.1\r
+HOST: #{MULTICAST_IP}:#{MULTICAST_PORT}\r
+MAN: "ssdp:discover"\r
+MX: #{response_wait_time}\r
+ST: #{search_target}\r
+\r
+        MSEARCH
+      end
+    end
+  end
+end

data/lib/druzy/upnp/ssdp.rb

@@ -0,0 +1,195 @@
+require 'core_ext/socket_patch'
+require 'eventmachine'
+require 'em-synchrony'
+require 'core_ext/to_upnp_s'
+require_relative 'ssdp/error'
+require_relative 'ssdp/network_constants'
+require_relative 'ssdp/listener'
+require_relative 'ssdp/searcher'
+require_relative 'ssdp/notifier'
+
+require_relative 'ssdp/broadcast_searcher'
+
+module Druzy
+  module Upnp
+  
+    # This is the main class for doing SSDP stuff.  You can have a look at child
+    # classes, but you'll probably want to just use these methods here.
+    #
+    # SSDP is "Simple Service Discovery Protocol", which lets you find and learn
+    # about UPnP devices on your network.  Of the six "steps" of UPnP (given in
+    # the UPnP spec--that's counting step 0), SSDP is what provides step 1, or the
+    # "discovery" step.
+    #
+    # Before you can do anything with any of the UPnP devices on your network, you
+    # need to +search+ your network to see what devices are available.  Once you've
+    # found what's available, you can then decide device(s) you'd like to control
+    # (that's where Control Points come in; take a look at Playful::ControlPoint).
+    # After searching, you should then +listen+ to the activity on your network.
+    # New devices on your network may come online (via +ssdp:alive+) and devices
+    # that you care about may go offline (via +ssdp:byebye+), in which case you
+    # probably shouldn't try to talk to them anymore.
+    #
+    # @todo Add docs for Playful::Device perspective.
+    class SSDP
+      include NetworkConstants
+  
+      # Opens a multicast UDP socket on 239.255.255.250:1900 and listens for
+      # alive and byebye notifications from devices.
+      #
+      # @param [Fixnum] ttl The TTL to use on the UDP socket.
+      #
+      # @return [Hash<Array>,Playful::SSDP::Listener] If the EventMachine reactor is
+      #   _not_ running, it returns two key/value pairs--one for
+      #   alive_notifications, one for byebye_notifications.  If the reactor _is_
+      #   running, it returns a Playful::SSDP::Listener so that that object can be
+      #   used however desired.  The latter method is used in Playful::ControlPoints
+      #   so that an object of that type can keep track of devices it cares about.
+      def self.listen(ttl=TTL)
+        alive_notifications = Set.new
+        byebye_notifications = Set.new
+  
+        listener = proc do
+          l = EM.open_datagram_socket(MULTICAST_IP, MULTICAST_PORT,
+            Playful::SSDP::Listener, ttl)
+          i = 0
+          EM.add_periodic_timer(5) { i += 5; Playful.log "Listening for #{i}\n" }
+          l
+        end
+  
+        if EM.reactor_running?
+          return listener.call
+        else
+          EM.synchrony do
+            l = listener.call
+  
+            alive_getter = Proc.new do |notification|
+              alive_notifications << notification
+              EM.next_tick { l.alive_notifications.pop(&live_getter) }
+            end
+            l.alive_notifications.pop(&alive_getter)
+  
+            byebye_getter = Proc.new do |notification|
+              byebye_notifications << notification
+              EM.next_tick { l.byebye_notifications.pop(&byebye_getter) }
+            end
+            l.byebye_notifications.pop(&byebye_getter)
+  
+            trap_signals
+          end
+        end
+  
+        {
+          alive_notifications: alive_notifications.to_a.flatten,
+          byebye_notifications: byebye_notifications.to_a.flatten
+        }
+      end
+  
+      # Opens a UDP socket on 0.0.0.0, on an ephemeral port, has Druzy::Upnp::SSDP::Searcher
+      # build and send the search request, then receives the responses.  The search
+      # will stop after +response_wait_time+.
+      #
+      # @param [String] search_target
+      #
+      # @param [Hash] options
+      #
+      # @option options [Fixnum] response_wait_time
+      # @option options [Fixnum] ttl
+      # @option options [Fixnum] m_search_count
+      # @option options [Boolean] do_broadcast_search Tells the search call to also send
+      #   a M-SEARCH over 255.255.255.255.  This is *NOT* part of the UPnP spec;
+      #   it's merely a hack for working with some types of devices that don't
+      #   properly implement the UPnP spec.
+      #
+      # @return [Array<Hash>,Playful::SSDP::Searcher] Returns a Hash that represents
+      #   the headers from the M-SEARCH response.  Each one of these can be passed
+      #   in to Playful::ControlPoint::Device.new to download the device's
+      #   description file, parse it, and interact with the device's devices
+      #   and/or services.  If the reactor is already running this will return a
+      #   a Playful::SSDP::Searcher which will make its accessors available so you
+      #   can get responses in real time.
+      def self.search(search_target=:all, options = {})
+        response_wait_time = options[:response_wait_time] || 5
+        ttl = options[:ttl] || TTL
+        do_broadcast_search = options[:do_broadcast_search]
+  
+        searcher_options = options
+        searcher_options.delete :do_broadcast_search
+  
+        responses = []
+        search_target = search_target.to_upnp_s
+  
+        multicast_searcher = proc do
+          EM.open_datagram_socket('0.0.0.0', 0, Druzy::Upnp::SSDP::Searcher,
+            search_target, searcher_options)
+        end
+  
+        broadcast_searcher = proc do
+          EM.open_datagram_socket('0.0.0.0', 0, Druzy::Upnp::SSDP::BroadcastSearcher,
+            search_target, response_wait_time, ttl)
+        end
+  
+        if EM.reactor_running?
+          return multicast_searcher.call
+        else
+          EM.synchrony do
+            ms = multicast_searcher.call
+  
+            ms.discovery_responses.subscribe do |notification|
+              responses << notification
+            end
+  
+            if do_broadcast_search
+              bs = broadcast_searcher.call
+  
+              bs.discovery_responses.subscribe do |notification|
+                responses << notification
+              end
+            end
+  
+            EM.add_timer(response_wait_time) { EM.stop }
+            trap_signals
+          end
+        end
+  
+        responses.flatten
+      end
+  
+      # @todo This is for Playful::Devices, which aren't implemented yet, and thus
+      #   this may not be working.
+      def self.notify(notification_type, usn, ddf_url, valid_for_duration=1800)
+        responses = []
+        notification_type = notification_type.to_upnp_s
+  
+        EM.synchrony do
+          s = send_notification(notification_type, usn, ddf_url, valid_for_duration)
+          EM.add_shutdown_hook { responses = s.discovery_responses }
+  
+          EM.add_periodic_timer(valid_for_duration) do
+            s = send_notification(notification_type, usn, ddf_url, valid_for_duration)
+          end
+  
+          trap_signals
+        end
+  
+        responses
+      end
+  
+      # @todo This is for Playful::Devices, which aren't implemented yet, and thus
+      #   this may not be working.
+      def self.send_notification(notification_type, usn, ddf_url, valid_for_duration)
+        EM.open_datagram_socket('0.0.0.0', 0, Druzy::Upnp::SSDP::Notifier, notification_type,
+          usn, ddf_url, valid_for_duration)
+      end
+  
+      private
+  
+      # Traps INT, TERM, and HUP signals and stops the reactor.
+      def self.trap_signals
+        trap('INT') { EM.stop }
+        trap('TERM') { EM.stop }
+        trap('HUP')  { EM.stop } if RUBY_PLATFORM !~ /mswin|mingw/
+      end
+    end
+  end
+end

data/lib/druzy/upnp/version.rb

@@ -0,0 +1,5 @@
+module Druzy
+  module Upnp
+    VERSION = '1.0.0'  
+  end
+end

data/lib/druzy/upnp.rb

@@ -0,0 +1,7 @@
+require_relative 'upnp/version'
+
+module Druzy
+	module Upnp
+
+	end
+end

data/lib/rack/upnp_control_point.rb

@@ -0,0 +1,70 @@
+require 'rack'
+require 'druzy/upnp/control_point'
+
+module Rack
+
+  # Middleware that allows your Rack app to keep tabs on devices that the
+  # {Playful::ControlPoint} has found.  UPnP devices that match the +search_type+
+  # are discovered and added to the list, then removed as those devices send out
+  # +ssdp:byebye+ notifications.  All of this depends on +EventMachine::Channel+s,
+  # and thus requires that an EventMachine reactor is running.  If you don't
+  # have one running, the {Playful::ControlPoint} will start one for you.
+  #
+  # @example Control all root devices
+  #
+  #   Thin::Server.start('0.0.0.0', 3000) do
+  #     use Rack::UPnPControlPoint, search_type: :root
+  #
+  #     map "/devices" do
+  #       run lambda { |env|
+  #         devices = env['upnp.devices']
+  #         friendly_names = devices.map(&:friendly_name).join("\n")
+  #         [200, {'Content-Type' => 'text/plain'}, [friendly_names]]
+  #       }
+  #     end
+  #   end
+  #
+  class UPnPControlPoint
+
+    # @param [Rack::Builder] app Your Rack application.
+    # @param [Hash] options Options to pass to the Playful::SSDP::Searcher.
+    # @see Playful::SSDP::Searcher
+    def initialize(app, options = {})
+      @app = app
+      @devices = []
+      options[:search_type] ||= :root
+      EM.next_tick { start_control_point(options[:search_type], options) }
+    end
+
+    # Creates and starts the {Playful::ControlPoint}, then manages the list of
+    # devices using the +EventMachine::Channel+ objects yielded in.
+    #
+    # @param [Symbol,String] search_type The device(s) you want to search for
+    #   and control.
+    # @param [Hash] options Options to pass to the Playful::SSDP::Searcher.
+    # @see Playful::SSDP::Searcher
+    def start_control_point(search_type, options)
+      @cp = ::Playful::ControlPoint.new(search_type, options)
+
+      @cp.start do |new_device_channel, old_device_channel|
+        new_device_channel.subscribe do |notification|
+          @devices << notification
+        end
+
+        old_device_channel.subscribe do |old_device|
+          @devices.reject! { |d| d.usn == old_device[:usn] }
+        end
+      end
+
+    end
+
+    # Adds the whole list of devices to <tt>env['upnp.devices']</tt> so that
+    # that list can be accessed from within your app.
+    #
+    # @param [Hash] env The Rack environment.
+    def call(env)
+      env['upnp.devices'] = @devices
+      @app.call(env)
+    end
+  end
+end