dnssd 1.1.0 → 1.2

data/lib/dnssd.rb

@@ -1,153 +1,182 @@
 require 'dnssd/dnssd'
+require 'socket'
 
 ##
-# DNSSD is a wrapper for Apple's DNS Service Discovery library.  The methods
-# DNSSD.enumerate_domains, DNSSD.browse(), DNSSD.register(), and
-# DNSSD.resolve() provide the basic API for making your applications DNS
-# Service Discovery aware.
+# DNSSD is a wrapper for the DNS Service Discovery library.
+#
+# DNSSD.announce and DNSSD::Reply.connect provide an easy-to-use way to
+# announce and connect to services.
+#
+# The methods DNSSD.enumerate_domains, DNSSD.browse, DNSSD.register, and
+# DNSSD.resolve provide the basic API for making your applications DNS \Service
+# Discovery aware.
 
 module DNSSD
-  VERSION = '1.1.0'
-end
 
-require 'dnssd/flags'
-require 'dnssd/reply'
-require 'dnssd/service'
-require 'dnssd/text_record'
+  ##
+  # The version of DNSSD you're using.
 
-=begin
+  VERSION = '1.2'
 
-module DNSSD
-  class MalformedDomain < Error; end
-  class MalformedPort < Error; end
+  ##
+  # Registers +socket+ with DNSSD as +name+.  If +service+ is omitted it is
+  # looked up using #getservbyport and the ports address.  +text_record+,
+  # +flags+ and +interface+ are used as in #register.
+  #
+  # Returns the Service created by registering the socket.  The Service will
+  # automatically be shut down when #close or #close_read is called on the
+  # socket.
+  #
+  # Only for bound TCP and UDP sockets.
 
-  def self.new_text_record(hash={})
-    TextRecord.new(hash)
-  end
+  def self.announce(socket, name, service = nil, text_record = nil, flags = 0,
+                    interface = DNSSD::InterfaceAny, &block)
+    _, port, _, address = socket.addr
 
-  class ServiceDescription
+    raise ArgumentError, 'socket not bound' if port == 0
 
-    class Location
-      attr_accessor :name, :port, :iface
-      def initialize(port, name=nil, iface=0)
-        @name = name
-        @port = port
-        @iface = iface
-      end
-    end
+    service ||= DNSSD.getservbyport port
 
-    def initialize(type, name, domain, location)
-      @type = type
-      @name = name
-      @domain = validate_domain(domain)
-      @location = validate_location(location)
-    end
+    proto = case socket
+            when TCPSocket then 'tcp'
+            when UDPSocket then 'udp'
+            else raise ArgumentError, 'tcp or udp sockets only'
+            end
 
-    def self.for_browse_notification(name, domain,
+    type = "_#{service}._#{proto}"
 
-    def stop
+    registrar = register(name, type, nil, port, text_record, flags, interface,
+                         &block)
+
+    socket.instance_variable_set :@registrar, registrar
+
+    def socket.close
+      result = super
       @registrar.stop
+      return result
     end
 
-    def validate_location(location)
-      unless(location.port.respond_to?(:to_int))
-        raise MalformedPort.new("#{location.port} is not a valid port number")
-      end
-      location
+    def socket.close_read
+      result = super
+      @registrar.stop
+      return result
     end
 
-    def validate_domain(domain)
-      unless(domain.empty? || domain =~ /^[a-z_]+$/)
-	      raise MalformedDomain.new("#{domain} is not a valid domain name")
-      end
-      domain
-    end
+    registrar
+  end
 
-    def advertise_and_confirm
-      thread = Thread.current
-       @registrar = register(@name, @type, @domain, @location.port, TextRecord.new) do |service, name, type, domain|
-        @name = name
-        @type = type
-        @domain = domain
-        thread.wakeup
-      end
-      Thread.stop
-    end
+  ##
+  # Asynchronous version of DNSSD::Service#browse
 
-    def self.advertise_http(name, port=80, domain="", iface=0, &block)
-      self.advertise("_http._tcp", name, port, domain, iface, &block)
+  def self.browse(type, domain = nil, flags = 0,
+                  interface = DNSSD::InterfaceAny, &block)
+    service = DNSSD::Service.new
+
+    Thread.start do
+      run(service, :browse, type, domain, flags, interface, &block)
     end
 
-    ##
-    # iface: Numerical interface (0 = all interfaces, This should be used for
-    # most applications)
+    service
+  end
+
+  ##
+  # Synchronous version of DNSSD::Service#browse
 
-    def self.advertise(type, name, port, domain="", iface=0, &block)
-      service_description = ServiceDescription.new(type, name, domain, Location.new(port,nil,iface))
-      service_description.advertise_and_confirm
-      yield service_description if block_given?
-      service_description
+  def self.browse!(type, domain = nil, flags = 0,
+                  interface = DNSSD::InterfaceAny, &block)
+    service = DNSSD::Service.new
+
+    run(service, :browse, type, domain, flags, interface, &block)
+  end
+
+  ##
+  # Asynchronous version of DNSSD::Service#enumerate_domains
+
+  def self.enumerate_domains(flags = DNSSD::Flags::BrowseDomains,
+                             interface = DNSSD::InterfaceAny, &block)
+    service = DNSSD::Service.new
+
+    Thread.start do
+      run(service, :enumerate_domains, flags, interface, &block)
     end
+
+    service
   end
 
-  class Browser
+  ##
+  # Synchronous version of DNSSD::Service#enumerate_domains
 
-    Context = Struct.new(:service, :name, :type, :domain, :operation, :interface)
+  def self.enumerate_domains!(flags = DNSSD::Flags::BrowseDomains,
+                              interface = DNSSD::InterfaceAny, &block)
+    service = DNSSD::Service.new
 
-    class Context
-      def ==(other)
-        self.to_s == other.to_s
-      end
+    run(service, :enumerate_domains, flags, interface, &block)
+  end
 
-      def to_s
-        "#{name}.#{type}.#{domain}"
-      end
+  ##
+  # Asynchronous version of DNSSD::Service#register
 
-      def eql?(other)
-        self == other
-      end
+  def self.register(name, type, domain, port, text_record = nil, flags = 0,
+                    interface = DNSSD::InterfaceAny, &block)
+    service = DNSSD::Service.new
 
-      def hash
-        to_s.hash
-      end
+    Thread.start do
+      run(service, :register, name, type, domain, port, nil, text_record,
+          flags, interface, &block)
     end
 
-    def on_change(&block)
-      @change_listener ||= []
-      @change_listeners << block
-    end
+    service
+  end
 
-    def on_add(&block)
-      @add_listeners || = []
-      @add_listeners << block
-    end
+  ##
+  # Synchronous version of DNSSD::Service#register
 
-    def on_remove(&block)
-      @remove_listeners || = []
-      @remove_listeners << block
-    end
+  def self.register!(name, type, domain, port, text_record = nil, flags = 0,
+                     interface = DNSSD::InterfaceAny, &block)
+    service = DNSSD::Service.new
 
-    def initialize(type, domain="")
-      @list = []
-      @browse_service = DNSSD::Protocol.browse(type, domain) do
-         |service, name, type, domain, operation, interface|
-         context = Context.new(service, name, type, domain, operation, interface)
-         puts "Name: #{name} Type: #{type} Domain: #{domain} Operation: #{operation} Interface: #{interface}"
-      end
-    end
+    run(service, :register, name, type, domain, port, nil, text_record, flags,
+        interface, &block)
+  end
 
-    def service_descriptions
-      @list.clone
-    end
+  ##
+  # Asynchronous version of DNSSD::Service#resolve
 
-    def stop
-      @browse_service.stop
-    end
+  def self.resolve(*args, &block)
+    service = DNSSD::Service.new
 
-    def self.for_http(domain="")
-      self.new("_http._tcp", domain)
+    Thread.start do
+      run(service, :resolve, *args, &block)
     end
+
+    service
+  end
+
+  ##
+  # Synchronous version of DNSSD::Service#resolve
+
+  def self.resolve!(*args, &block)
+    service = DNSSD::Service.new
+
+    run(service, :resolve, *args, &block)
+  end
+
+  ##
+  # Dispatches +args+ and +block+ to +method+ on +service+ and ensures
+  # +service+ is shut down after use.
+
+  def self.run(service, method, *args, &block)
+    service.send(method, *args, &block)
+
+    service
+  ensure
+    service.stop unless service.stopped?
   end
+
 end
 
-=end
+require 'dnssd/flags'
+require 'dnssd/reply'
+require 'dnssd/service'
+require 'dnssd/text_record'
+

data/lib/dnssd/flags.rb

@@ -22,6 +22,9 @@ class DNSSD::Flags
     end
   end
 
+  ##
+  # Bitfield with all valid flags set
+
   ALL_FLAGS = FLAGS.values.inject { |flag, all| flag | all }
 
   ##
@@ -71,16 +74,25 @@ class DNSSD::Flags
     verify
   end
 
+  ##
+  # Returns an Array of flag names
+
   def to_a
     FLAGS.map do |name, value|
       (@flags & value == value) ? name : nil
     end.compact
   end
 
-  def to_i # :nodoc:
+  ##
+  # Flags as a bitfield
+
+  def to_i
     @flags
   end
 
+  ##
+  # Trims the flag list down to valid flags
+
   def verify
     @flags &= ALL_FLAGS
 

data/lib/dnssd/reply.rb

@@ -29,7 +29,7 @@ class DNSSD::Reply
   attr_reader :port
 
   ##
-  # The service associated with the reply, see DNSSD::Service
+  # The DNSSD::Service associated with the reply
 
   attr_reader :service
 
@@ -48,6 +48,9 @@ class DNSSD::Reply
 
   attr_reader :type
 
+  ##
+  # Creates a DNSSD::Reply from +service+ and +flags+
+
   def self.from_service(service, flags)
     reply = new
     reply.instance_variable_set :@service, service
@@ -55,6 +58,52 @@ class DNSSD::Reply
     reply
   end
 
+  ##
+  # Connects to this Reply.  If +target+ and +port+ are missing, DNSSD.resolve
+  # is automatically called.  +family+ can be used to select a particular
+  # address family.
+
+  def connect(family = Socket::AF_UNSPEC)
+    unless target and port then
+      value = nil
+
+      DNSSD.resolve! self do |reply|
+        value = reply
+        break
+      end
+
+      return value.connect
+    end
+
+    socktype = case protocol
+               when 'tcp' then Socket::SOCK_STREAM
+               when 'udp' then Socket::SOCK_DGRAM
+               else raise ArgumentError, "invalid protocol #{protocol}"
+               end
+
+    addresses = Socket.getaddrinfo target, port, family, socktype
+
+    socket = nil
+
+    addresses.each do |address|
+      begin
+        case protocol
+        when 'tcp' then
+          socket = TCPSocket.new address[3], port
+        when 'udp' then
+          socket = UDPSocket.new
+          socket.connect address[3], port rescue next
+        end
+
+        return socket
+      rescue
+        next
+      end
+    end
+
+    raise DNSSD::Error, "unable to connect to #{target}:#{port}" unless socket
+  end
+
   ##
   # The full service domain name, see DNSS::Service#fullname
 
@@ -62,12 +111,29 @@ class DNSSD::Reply
     DNSSD::Service.fullname @name.gsub("\032", ' '), @type, @domain
   end
 
-  def inspect
+  def inspect # :nodoc:
     "#<%s:0x%x %p type: %s domain: %s interface: %s flags: %s>" % [
       self.class, object_id, @name, @type, @domain, @interface, @flags
     ]
   end
 
+  ##
+  # Protocol of this service
+
+  def protocol
+    type.split('.').last.sub '_', ''
+  end
+
+  ##
+  # Service name as in Socket.getservbyname
+
+  def service_name
+    type.split('.').first.sub '_', ''
+  end
+
+  ##
+  # Sets #name, #type and #domain from +fullname+
+
   def set_fullname(fullname)
     fullname = fullname.gsub(/\\([0-9]+)/) do $1.to_i.chr end
     fullname = fullname.scan(/(?:[^\\.]|\\\.)+/).map do |part|
@@ -79,6 +145,9 @@ class DNSSD::Reply
     @domain = fullname.last + '.'
   end
 
+  ##
+  # Sets #name, #type and #domain
+
   def set_names(name, type, domain)
     set_fullname [name, type, domain].join('.')
   end

data/lib/dnssd/service.rb

@@ -1,15 +1,158 @@
+require 'thread'
+
+##
+# A DNSSD::Service may be used for one DNS-SD call at a time.  Between calls
+# the service must be stopped.  A single service can be reused multiple times.
+#
+# DNSSD::Service provides the raw DNS-SD functions via the _ variants.
+
 class DNSSD::Service
 
   ##
-  # Access the services underlying thread.  Returns nil if the service is
-  # synchronous.
+  # Creates a new DNSSD::Service
+
+  def initialize
+    @replies = []
+    @continue = true
+    @thread = nil
+  end
+
+  ##
+  # Browse for services.
+  #
+  # For each service found a DNSSD::Reply object is yielded.
+  #
+  #   service = DNSSD::Service.new
+  #   timeout 6 do
+  #     service.browse '_http._tcp' do |r|
+  #       puts "Found HTTP service: #{r.name}"
+  #     end
+  #   rescue Timeout::Error
+  #   end
+
+  def browse(type, domain = nil, flags = 0, interface = DNSSD::InterfaceAny,
+             &block)
+    check_domain domain
+    interface = DNSSD.interface_index interface unless Integer === interface
+
+    raise DNSSD::Error, 'service in progress' if started?
+
+    _browse type, domain, flags.to_i, interface
+
+    process(&block)
+  end
 
-  attr_reader :thread
+  ##
+  # Raises an ArgumentError if +domain+ is too long including NULL terminator
+  # and trailing '.'
+
+  def check_domain(domain)
+    return unless domain
+    raise ArgumentError, 'domain name string is too long' if
+      domain.length >= MAX_DOMAIN_NAME - 1
+  end
+
+  ##
+  # Enumerate domains available for browsing and registration.
+  #
+  # For each domain found a DNSSD::Reply object is passed to block with
+  # #domain set to the enumerated domain.
+  #
+  #   available_domains = []
+  #   
+  #   timeout(2) do
+  #     DNSSD.enumerate_domains! do |r|
+  #       available_domains << r.domain
+  #     end
+  #   rescue TimeoutError
+  #   end
+  #   
+  #   p available_domains
+
+  def enumerate_domains(flags = DNSSD::Flags::BrowseDomains,
+                        interface = DNSSD::InterfaceAny, &block)
+    interface = DNSSD.interface_index interface unless Integer === interface
+
+    raise DNSSD::Error, 'service in progress' if started?
+
+    _enumerate_domains flags.to_i, interface
+
+    process(&block)
+  end
   
-  def inspect
+  def inspect # :nodoc:
     stopped = stopped? ? 'stopped' : 'running'
     "#<%s:0x%x %s>" % [self.class, object_id, stopped]
   end
 
+  def process
+    @thread = Thread.current
+
+    while @continue do
+      _process if @replies.empty?
+      yield @replies.shift until @replies.empty?
+    end
+
+    @thread = nil
+
+    self
+  end
+
+  ##
+  # Register a service.  A DNSSD::Reply object is passed to the optional block
+  # when the registration completes.
+  #
+  #   DNSSD.register! "My Files", "_http._tcp", nil, 8080 do |r|
+  #     puts "successfully registered: #{r.inspect}"
+  #   end
+
+  def register(name, type, domain, port, host = nil, text_record = nil,
+               flags = 0, interface = DNSSD::InterfaceAny, &block)
+    check_domain domain
+    interface = DNSSD.interface_index interface unless Integer === interface
+
+    raise DNSSD::Error, 'service in progress' if started?
+
+    _register name, type, domain, host, port, text_record, flags.to_i, interface
+
+    block = proc { } unless block
+
+    process(&block)
+  end
+
+  ##
+  # Resolve a service discovered via #browse.
+  #
+  # +name+ may be either the name of the service found or a DNSSD::Reply from
+  # DNSSD::Service#browse.  When +name+ is a DNSSD::Reply, +type+ and +domain+
+  # are automatically filled in, otherwise the service type and domain must be
+  # supplied.
+  #
+  # The service is resolved to a target host name, port number, and text
+  # record, all contained in the DNSSD::Reply object passed to the required
+  # block.
+  #
+  # The returned service can be used to control when to stop resolving the
+  # service (see DNSSD::Service#stop).
+  #
+  #   s = DNSSD.resolve "foo bar", "_http._tcp", "local" do |r|
+  #     p r
+  #   end
+  #   sleep 2
+  #   s.stop
+
+  def resolve(name, type = name.type, domain = name.domain, flags = 0,
+              interface = DNSSD::InterfaceAny, &block)
+    name = name.name if DNSSD::Reply === name
+    check_domain domain
+    interface = DNSSD.interface_index interface unless Integer === interface
+
+    raise DNSSD::Error, 'service in progress' if started?
+
+    _resolve name, type, domain, flags.to_i, interface
+
+    process(&block)
+  end
+
 end