ruby-growl 3.0 → 4.0

data/.autotest

@@ -0,0 +1,16 @@
+require 'autotest/restart'
+
+Autotest.add_hook :initialize do |at|
+  at.add_exception '.git'
+  at.testlib = 'minitest/autorun'
+  at.unit_diff = 'cat'
+
+  def at.path_to_classname s
+    sep = File::SEPARATOR
+    f = s.sub(/^test#{sep}/, '').sub(/\.rb$/, '').split(sep)
+    f = f.map { |path| path.split(/_|(\d+)/).map { |seg| seg.capitalize }.join }
+    f = f.map { |path| path =~ /^Test/ ? path : "Test#{path}"  }
+    f.join('::').gsub('Gntp', 'GNTP').gsub('Udp', 'UDP')
+  end
+end
+

data/History.txt

@@ -1,3 +1,18 @@
+=== 4 / 2012-04-04
+
+* API changes:
+  * Growl is now a wrapper for Growl::UDP (1.2 and older) and Growl::GNTP (1.3
+    and newer).  The main difference is that notifications need to be
+    registered with Growl#add_notification instead of via Growl#initialize.
+  * Ruby 1.9.2 or newer is required to use ruby-growl
+
+* Major enhancements
+  * Added GNTP protocol support for registration and notification including
+    application and notification icons and callbacks.
+  * Moved UDP protocol support to Growl::UDP
+  * Growl automatically determines if the growl server supports GNTP or UDP
+    and uses the best protocol.
+
 === 3.0 / 2010-09-11
 
 * Major enhancement

data/Manifest.txt

@@ -1,7 +1,13 @@
+.autotest
 History.txt
 Manifest.txt
 README.txt
 Rakefile
 bin/growl
 lib/ruby-growl.rb
-test/test_ruby_growl.rb
+lib/ruby-growl/gntp.rb
+lib/ruby-growl/ruby_logo.rb
+lib/ruby-growl/udp.rb
+lib/uri/x_growl_resource.rb
+test/test_growl_gntp.rb
+test/test_growl_udp.rb

data/README.txt

@@ -4,23 +4,27 @@
 
 == DESCRIPTION:
 
-A pure-ruby growl notifier.  ruby-growl allows you to perform Growl
-notification via UDP from machines without growl installed (for example,
-non-OSX machines).
+A pure-ruby growl notifier for UDP and GNTP growl protocols.  ruby-growl
+allows you to perform Growl notifications from machines without growl
+installed (for example, non-OSX machines).
 
-What's Growl?  Growl is a really cool "global notification system for Mac OS
-X".  See http://growl.info/
+What is growl?  Growl is a really cool "global notification system originally
+for Mac OS X".
 
-See also the Ruby Growl bindings in Growl's subversion repository:
-http://growl.info/documentation/growl-source-install.php
+You can receive Growl notifications on various platforms and send them from
+any machine that runs Ruby.
 
-ruby-growl also contains a command-line notification tool named 'growl'.  Where
-possible, it isoption-compatible with growlnotify.  (Use --priority instead of
--p.)
+OS X: http://growl.info
+Windows: http://www.growlforwindows.com/gfw/
+Linux: http://github.com/mattn/growl-for-linux
+
+ruby-growl also contains a command-line notification tool named 'growl'.  It
+is almost completely option-compatible with growlnotify.  (All except for -p
+is supported, use --priority instead.)
 
 == FEATURES/PROBLEMS:
 
-* Requires "Listen for incoming notifications" enabled
+* Requires "Listen for incoming notifications" enabled on the growl server
 
 == INSTALL:
 

data/Rakefile

@@ -3,10 +3,13 @@ require 'hoe'
 
 Hoe.plugin :git
 Hoe.plugin :minitest
+Hoe.plugin :travis
 
 Hoe.spec 'ruby-growl' do
   developer 'Eric Hodel', 'drbrain@segment7.net'
 
-  spec_extras['required_ruby_version'] = '> 1.8.6'
+  spec_extras['required_ruby_version'] = '>= 1.9.2'
+
+  extra_deps << ['uuid', '~> 2.3', '>= 2.3.5']
 end
 

data/bin/growl

@@ -1,4 +1,4 @@
-#!/usr/local/bin/ruby -w
+#!/usr/local/bin/ruby
 
 require 'ruby-growl'
 

data/lib/ruby-growl.rb

@@ -1,149 +1,81 @@
-#!/usr/local/bin/ruby -w
-
 require 'digest/md5'
 require 'socket'
 
+begin
+  require 'dnssd'
+rescue LoadError
+end
+
 ##
-# ruby-growl allows you to perform Growl notification via UDP from machines
-# without growl installed (for example, non-OSX machines).
+# ruby-growl allows you to perform Growl notifications from machines without
+# growl installed (for example, non-OSX machines).
 #
-# What's Growl?  Growl is a really cool "global notification system for Mac OS
-# X".  See http://growl.info/
+# In version 4, the Growl class is a wrapper for Growl::UDP and Growl::GNTP.
+# The GNTP protocol allows setting icons for notifications and callbacks.  To
+# upgrade from version 3 replace the notification names passed to initialize
+# with a call to #add_notification.
 #
-# You'll need a Mac to recieve Growl notifications, but you can send Growl
-# notifications from any UDP-capable machine that runs Ruby.
+# Basic usage:
 #
-# See also the Ruby Growl bindings in Growl's subversion repository:
-# http://growl.info/documentation/growl-source-install.php
+#   require 'ruby-growl'
 #
-# ruby-growl also contains a command-line notification tool named 'growl'.  It
-# is almost completely option-compatible with growlnotify.  (All except for -p
-# is supported, use --priority instead.)
+#   g = Growl.new "localhost", "ruby-growl"
+#   g.add_notification "ruby-growl Notification"
+#   g.notify "ruby-growl Notification", "It came from ruby-growl!",
+#            "Greetings!"
 #
-# = Synopsis
+# For GNTP users, ruby-growl ships with the Ruby icon from the {Ruby Visual
+# Identity Team}[http://rubyidentity.org/]:
 #
-#   g = Growl.new "127.0.0.1", "ruby-growl",
-#                 ["ruby-growl Notification"]
-#   g.notify "ruby-growl Notification", "It Came From Ruby-Growl",
-#            "Greetings!"
+#   require 'ruby-growl'
+#   require 'ruby-growl/ruby_logo'
+#
+#   g = Growl.new "localhost", "ruby-growl"
+#   g.add_notification("notification", "ruby-growl Notification",
+#                      Growl::RUBY_LOGO_PNG)
+#   g.notify "notification", "It came from ruby-growl", "Greetings!"
+#
+# See Growl::UDP and Growl::GNTP for protocol-specific API.
 
 class Growl
 
   ##
-  # The Ruby that ships with Tiger has a broken #pack, so 'v' means network
-  # byte order instead of 'n'.
+  # ruby-growl version
 
-  BROKEN_PACK = [1].pack("n") != "\000\001" # :nodoc:
-
-  little_endian = [1].pack('V*') == [1].pack('L*')
-  little_endian = !little_endian if BROKEN_PACK
+  VERSION = '4.0'
 
   ##
-  # Endianness of this machine
-
-  LITTLE_ENDIAN = little_endian
+  # Growl error base class
 
-  ##
-  # ruby-growl Version
-
-  VERSION = '3.0'
-
-  ##
-  # Growl Network Registration Packet +pack+ Format
-  #--
-  # Format:
-  #
-  #   struct GrowlNetworkRegistration {
-  #     struct GrowlNetworkPacket {
-  #       unsigned char version;
-  #       unsigned char type;
-  #     } __attribute__((packed));
-  #     unsigned short appNameLen;
-  #     unsigned char numAllNotifications;
-  #     unsigned char numDefaultNotifications;
-  #     /*
-  #      *  Variable sized. Format:
-  #      *  <application name><all notifications><default notifications><checksum>
-  #      *  where <all notifications> is of the form (<length><name>){num} and
-  #      *  <default notifications> is an array of indices into the all notifications
-  #      *  array, each index being 8 bits.
-  #      */
-  #     unsigned char data[];
-  #   } __attribute__((packed));
-
-  GNR_FORMAT = "CCnCCa*"
-
-  GNR_FORMAT.gsub!(/n/, 'v') if BROKEN_PACK
-
-  ##
-  # Growl Network Notification Packet +pack+ Format
-  #--
-  # Format:
-  #
-  #   struct GrowlNetworkNotification {
-  #     struct GrowlNetworkPacket {
-  #       unsigned char version;
-  #       unsigned char type;
-  #     } __attribute__((packed));
-  #     struct GrowlNetworkNotificationFlags {
-  #       unsigned reserved: 12;
-  #       signed   priority: 3;
-  #       unsigned sticky:   1;
-  #     } __attribute__((packed)) flags; //size = 16 (12 + 3 + 1)
-  #     unsigned short nameLen;
-  #     unsigned short titleLen;
-  #     unsigned short descriptionLen;
-  #     unsigned short appNameLen;
-  #     /*
-  #      *  Variable sized. Format:
-  #      *  <notification name><title><description><application name><checksum>
-  #      */
-  #     unsigned char data[];
-  #   } __attribute__((packed));
-
-  GNN_FORMAT = "CCnnnnna*"
-
-  GNN_FORMAT.gsub!(/n/, 'v') if BROKEN_PACK
-
-  # For litle endian machines the NetworkNotificationFlags aren't in network
-  # byte order
-
-  GNN_FORMAT.sub!((BROKEN_PACK ? 'v' : 'n'), 'v') if LITTLE_ENDIAN
-
-  ##
-  # Growl UDP Port
-
-  GROWL_UDP_PORT = 9887
-
-  ##
-  # Growl Protocol Version
-
-  GROWL_PROTOCOL_VERSION = 1
-
-  ##
-  # Growl Registration Packet Id
-
-  GROWL_TYPE_REGISTRATION = 0
+  class Error < RuntimeError
+  end
 
   ##
-  # Growl Notification Packet Id
+  # Password for authenticating and encrypting requests.
 
-  GROWL_TYPE_NOTIFICATION = 1
+  attr_accessor :password
 
   ##
   # List of hosts accessible via dnssd
 
-  def self.list
-    require 'dnssd'
+  def self.list type
+    raise 'you must gem install dnssd' unless Object.const_defined? :DNSSD
+
+    require 'timeout'
 
     growls = []
 
-    DNSSD.browse! '_growl._tcp' do |reply|
-      next unless reply.flags.add?
+    begin
+      Timeout.timeout 10 do
+        DNSSD.browse! type do |reply|
+          next unless reply.flags.add?
 
-      growls << reply
+          growls << reply
 
-      break unless reply.flags.more_coming?
+          break unless reply.flags.more_coming?
+        end
+      end
+    rescue Timeout::Error
     end
 
     hosts = []
@@ -156,8 +88,6 @@ class Growl
     end
 
     hosts.uniq
-  rescue LoadError
-    raise 'you must gem install dnssd'
   end
 
   ##
@@ -172,10 +102,10 @@ class Growl
     end
 
     notify_type = options[:notify_type]
-    notify_types = [notify_type]
 
-    g = new(options[:host], options[:name], notify_types, notify_types,
-            options[:password])
+    g = new options[:host], options[:name]
+    g.add_notification notify_type
+    g.password = options[:password]
 
     g.notify(notify_type, options[:title], message, options[:priority],
              options[:sticky])
@@ -188,15 +118,15 @@ class Growl
     require 'optparse'
 
     options = {
-      :host        => nil,
-      :message     => nil,
-      :name        => "ruby-growl",
-      :notify_type => "ruby-growl Notification",
-      :password    => nil,
-      :priority    => 0,
-      :sticky      => false,
-      :title       => "",
-      :list        => false,
+      host:        nil,
+      message:     nil,
+      name:        "ruby-growl",
+      notify_type: "ruby-growl Notification",
+      password:    nil,
+      priority:    0,
+      sticky:      false,
+      title:       "",
+      list:        false,
     }
 
     opts = OptionParser.new do |o|
@@ -277,7 +207,11 @@ Synopsis:
 
     if options[:list] then
       begin
-        puts list
+        puts 'Growl GNTP hosts:'
+        puts list '_gntp._tcp'
+        puts
+        puts 'Growl UDP hosts:'
+        puts list '_growl._tcp'
       rescue => e
         raise unless e.message =~ /gem install dnssd/
 
@@ -290,165 +224,105 @@ Synopsis:
   end
 
   ##
-  # Creates a new Growl notifier and automatically registers any notifications
-  # with the remote machine.
-  #
-  # +host+ is the host to contact.
-  #
-  # +app_name+ is the name of the application sending the notifications.
-  #
-  # +all_notifies+ is a list of notification types your application sends.
-  #
-  # +default_notifies+ is a list of notification types that are turned on by
-  # default.
-  #
-  # I'm not sure about what +default_notifies+ is supposed to be set to, since
-  # there is a comment that says "not a subset of all_notifies" in the code.
-  #
-  # +password+ is the password needed to send notifications to +host+.
-
-  def initialize(host, app_name, all_notifies, default_notifies = nil,
-                 password = nil)
-    @socket = UDPSocket.open
-    # FIXME This goes somewhere else
-    @socket.connect host, GROWL_UDP_PORT
-    @app_name = app_name
-    @all_notifies = all_notifies
-    @default_notifies = default_notifies.nil? ? all_notifies : default_notifies
-    @password = password
-
-    register
-  end
-
-  ##
-  # Sends a notification.
+  # Creates a new growl basic notifier for +host+ and +application_name+.
   #
-  # +notify_type+ is the type of notification to send.
+  # +growl_type+ is used to specify the type of growl server to connect to.
+  # The following values are allowed:
   #
-  # +title+ is a title for the notification.
+  # nil::
+  #   Automatically determine the growl type.  If a GNTP server is not found
+  #   then ruby-growl chooses UDP.
+  # 'GNTP'::
+  #   Use GNTP connections.  GNTP is supported by Growl 1.3 and newer and by
+  #   Growl for Windows.
+  # 'UDP'::
+  #   Uses the UDP growl protocol.  UDP growl is supported by Growl 1.2 and
+  #   older.
   #
-  # +message+ is the body of the notification.
-  #
-  # +priority+ is the priorty of message to send.
-  #
-  # +sticky+ makes the notification stick until clicked.
+  # You can use <tt>growl --list</tt> to see growl servers on your local
+  # network.
 
-  def notify(notify_type, title, message, priority = 0, sticky = false)
-    raise "Unknown Notification" unless @all_notifies.include? notify_type
-    raise "Invalid Priority" unless priority >= -2 and priority <= 2
+  def initialize host, application_name, growl_type = nil
+    @host = host
+    @application_name = application_name
 
-    send notification_packet(notify_type, title, message, priority, sticky)
-  end
+    @notifications = {}
+    @password      = nil
 
-  ##
-  # Registers the notification types with +host+.
-
-  def register
-    send registration_packet
+    @growl_type = choose_implementation growl_type
   end
 
   ##
-  # Sends a Growl packet
+  # Adds a notification named +name+ to the basic notifier.  For GNTP servers
+  # you may specify a +display_name+ and +icon+ and set the default +enabled+
+  # status.
 
-  def send(packet)
-    set_sndbuf packet.length
-    @socket.send packet, 0
-    @socket.flush
+  def add_notification name, display_name = nil, icon = nil, enabled = true
+    @notifications[name] = display_name, icon, enabled
   end
 
-  ##
-  # Builds a Growl registration packet
-
-  def registration_packet
-    length = 0
-    data = []
-    data_format = ""
-
-    packet = [
-      GROWL_PROTOCOL_VERSION,
-      GROWL_TYPE_REGISTRATION
-    ]
+  def choose_implementation type # :nodoc:
+    raise ArgumentError,
+          "type must be \"GNTP\", \"UDP\" or nil; was #{type.inspect}" unless
+      ['GNTP', 'UDP', nil].include? type
 
-    packet << @app_name.bytesize
-    packet << @all_notifies.length
-    packet << @default_notifies.length
+    return type if type
 
-    data << @app_name
-    data_format = "a#{@app_name.bytesize}"
-
-    @all_notifies.each do |notify|
-      data << notify.length
-      data << notify
-      data_format << "na#{notify.length}"
-    end
-
-    @default_notifies.each do |notify|
-      data << @all_notifies.index(notify) if @all_notifies.include? notify
-      data_format << "C"
-    end
+    TCPSocket.open @host, Growl::GNTP::PORT do end
 
-    data_format.gsub!(/n/, 'v') if BROKEN_PACK
-
-    data = data.pack data_format
-
-    packet << data
-
-    packet = packet.pack GNR_FORMAT
-
-    checksum = Digest::MD5.new << packet
-    checksum.update @password unless @password.nil?
-
-    packet << checksum.digest
-
-    return packet
+    'GNTP'
+  rescue SystemCallError
+    'UDP'
   end
 
   ##
-  # Builds a Growl notification packet
-
-  def notification_packet(name, title, description, priority, sticky)
-    flags = 0
-    data = []
-
-    packet = [
-      GROWL_PROTOCOL_VERSION,
-      GROWL_TYPE_NOTIFICATION,
-    ]
+  # Sends a notification of type +name+ with the given +title+, +message+,
+  # +priority+ and +sticky+ settings.
+
+  def notify name, title, message, priority = 0, sticky = false
+    case @growl_type
+    when 'GNTP' then
+      notify_gntp name, title, message, priority, sticky
+    when 'UDP'  then
+      notify_udp name, title, message, priority, sticky
+    else
+      raise Growl::Error, "bug, unknown growl type #{@growl_type.inspect}"
+    end
 
-    flags = 0
-    flags |= ((0x7 & priority) << 1) # 3 bits for priority
-    flags |= 1 if sticky # 1 bit for sticky
+    self
+  end
 
-    packet << flags
-    packet << name.bytesize
-    packet << title.length
-    packet << description.bytesize
-    packet << @app_name.bytesize
+  def notify_gntp name, title, message, priority, sticky # :nodoc:
+    growl = Growl::GNTP.new @host, @application_name
+    growl.password = @password
 
-    data << name
-    data << title
-    data << description
-    data << @app_name
+    @notifications.each do |name, details|
+      growl.add_notification name, *details
+    end
 
-    packet << data.join
-    packet = packet.pack GNN_FORMAT
+    growl.register
 
-    checksum = Digest::MD5.new << packet
-    checksum.update @password unless @password.nil?
+    growl.notify name, title, message, priority, sticky
+  end
 
-    packet << checksum.digest
+  def notify_udp name, title, message, priority, sticky # :nodoc:
+    all_notifications = @notifications.keys
+    default_notifications = @notifications.select do |name, (_, _, enabled)|
+      enabled
+    end.map do |name,|
+      name
+    end
 
-    return packet
-  end
+    notification = all_notifications.first
 
-  ##
-  # Set the size of the send buffer
-  #--
-  # Is this truly necessary?
+    growl = Growl::UDP.new(@host, @application_name, all_notifications,
+                           default_notifications, @password)
 
-  def set_sndbuf(length)
-    @socket.setsockopt Socket::SOL_SOCKET, Socket::SO_SNDBUF, length
+    growl.notify name, title, message, priority, sticky
   end
 
 end
 
+require 'ruby-growl/gntp'
+require 'ruby-growl/udp'
+