playful 0.1.0.alpha.1

data/lib/playful/ssdp.rb

@@ -0,0 +1,195 @@
+require_relative '../core_ext/socket_patch'
+require 'eventmachine'
+require 'em-synchrony'
+require_relative '../core_ext/to_upnp_s'
+require_relative 'logger'
+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 Playful
+
+  # 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 LogSwitch::Mixin
+    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 Playful::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, Playful::SSDP::Searcher,
+          search_target, searcher_options)
+      end
+
+      broadcast_searcher = proc do
+        EM.open_datagram_socket('0.0.0.0', 0, Playful::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, Playful::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

data/lib/playful/ssdp/broadcast_searcher.rb

@@ -0,0 +1,114 @@
+require_relative '../../core_ext/socket_patch'
+require_relative '../logger'
+require_relative 'network_constants'
+require 'ipaddr'
+require 'socket'
+require 'eventmachine'
+
+
+# TODO: DRY this up!!  (it's mostly the same as Playful::SSDP::MulticastConnection)
+module Playful
+  class SSDP
+    class BroadcastSearcher < EventMachine::Connection
+      include LogSwitch::Mixin
+      include EventMachine::Deferrable
+      include Playful::SSDP::NetworkConstants
+
+      # @return [Array] The list of responses from the current discovery request.
+      attr_reader :discovery_responses
+
+      attr_reader :available_responses
+      attr_reader :byebye_responses
+
+      def initialize(search_target, response_wait_time, ttl=TTL)
+        @ttl = ttl
+        @discovery_responses = []
+        @alive_notifications = []
+        @byebye_notifications = []
+
+        setup_broadcast_socket
+
+        @search = m_search(search_target, response_wait_time)
+      end
+
+      def post_init
+        if send_datagram(@search, BROADCAST_IP, MULTICAST_PORT) > 0
+          log "Sent broadcast datagram search:\n#{@search}"
+        end
+      end
+
+      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
+
+      # 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
+
+      def receive_data(response)
+        ip, port = peer_info
+        log "Response from #{ip}:#{port}:\n#{response}\n"
+        parsed_response = parse(response)
+
+        if parsed_response.has_key? :nts
+          if parsed_response[:nts] == 'ssdp:alive'
+            @alive_notifications << parsed_response
+          elsif parsed_response[:nts] == 'ssdp:bye-bye'
+            @byebye_notifications << parsed_response
+          else
+            raise "Unknown NTS value: #{parsed_response[:nts]}"
+          end
+        else
+          @discovery_responses << parsed_response
+        end
+      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/
+          log 'Received response as a single-line String.  Discarding.'
+          log "Bad response looked like:\n#{data}"
+          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 brodcasting.
+      def setup_broadcast_socket
+        set_sock_opt(Socket::SOL_SOCKET, Socket::SO_BROADCAST, true)
+      end
+    end
+  end
+end

data/lib/playful/ssdp/error.rb

@@ -0,0 +1,6 @@
+module Playful
+  class SSDP
+    class Error < StandardError
+    end
+  end
+end

data/lib/playful/ssdp/listener.rb

@@ -0,0 +1,38 @@
+require_relative 'multicast_connection'
+
+
+class Playful::SSDP::Listener < Playful::SSDP::MulticastConnection
+  include LogSwitch::Mixin
+
+  # @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
+    log "Response from #{ip}:#{port}:\n#{response}\n"
+    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/playful/ssdp/multicast_connection.rb

@@ -0,0 +1,112 @@
+require_relative '../../core_ext/socket_patch'
+require_relative 'network_constants'
+require_relative '../logger'
+require_relative 'error'
+require 'ipaddr'
+require 'socket'
+require 'eventmachine'
+require 'em-synchrony'
+
+
+module Playful
+  class SSDP
+    class MulticastConnection < EventMachine::Connection
+      include Playful::SSDP::NetworkConstants
+      include LogSwitch::Mixin
+
+      # @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/
+          log 'Received response as a single-line String.  Discarding.'
+          log "Bad response looked like:\n#{data}"
+          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