net-ping 1.6.2-universal-mingw32

data/doc/ping.txt

@@ -0,0 +1,274 @@
+= Description
+   A simple Ruby interface to the 'ping' command.
+
+= Synopsis
+   require 'net/ping'
+   include Net
+
+   Ping::TCP.service_check = true
+
+   pt = Net::Ping::TCP.new(host)
+   pu = Net::Ping::UDP.new(host)
+   pe = Net::Ping::External.new(host)
+   ph = Net::Ping::HTTP.new(uri)
+
+   if pt.ping
+      puts "TCP ping successful"
+   else
+      puts "TCP ping unsuccessful: " +  pt.exception
+   end
+
+   if pu.ping
+      puts "UDP ping successful"
+   else
+      puts "UDP ping unsuccessful: " +  pu.exception
+   end
+
+   if pe.ping
+      puts "External ping successful"
+   else
+      puts "External ping unsuccessful: " +  pe.exception
+   end
+
+   if ph.ping?
+      puts "HTTP ping successful"
+   else
+      puts "HTTP ping unsuccessful: " + ph.exception
+   end
+
+= Ping Classes
+   * Ping::TCP
+   * Ping::UDP
+   * Ping::External
+   * Ping::HTTP
+   * Ping::ICMP
+   * Ping::WMI
+   * Ping::LDAP
+
+   All Ping classes are children of the Ping parent class (which should
+   never be instantiated directly).
+
+   The Ping::ICMP class requires root privileges on UNIX systems.
+
+   The Ping::WMI class only works on MS Windows.
+
+== Net::Ping
+Net::Ping.new(host=nil, port=7, timeout=5)
+   Creates and returns a new Ping object.  If the host is not specified
+   in the constructor then it must be specified in the ping method.
+
+== Net::Ping::TCP
+Ping::TCP.service_check
+   Returns the setting for how ECONNREFUSED is handled. By default, this is
+   set to false, i.e. an ECONNREFUSED error is considered a failed ping.
+
+Ping::TCP.service_check=(bool)
+   Sets the behavior for how ECONNREFUSED is handled. By default, this is
+   set to false, i.e. an ECONNREFUSED error is considered a failed ping.
+
+Ping::TCP#ping(host=nil)
+   Attempts to open a connection using TCPSocket with a +host+ specified
+   either here or in the constructor.  A successful open means the ping was
+   successful and true is returned.  Otherwise, false is returned.
+
+== Net::Ping::UDP
+Ping::UDP#ping
+   Attempts to open a connection using UDPSocket and sends the value of
+   Ping::UDP#data as a string across the socket.  If the return string matches,
+   then the ping was successful and true is returned.  Otherwise, false is
+   returned.
+	
+Ping::UDP#data
+   Returns the string that is sent across the UDP socket.
+	
+Ping::UDP#data=(string)
+   Sets the string that is sent across the UDP socket.  The default is "ping".
+   Note that the +string+ cannot be larger than MAX_DATA (64 characters).
+
+== Net::Ping::External
+Ping::External#ping
+   Uses the 'open3' module and calls your system's local 'ping' command with
+   various options, depending on platform.  If nothing is sent to stderr, the
+   ping was successful and true is returned.  Otherwise, false is returned.
+
+   The MS Windows platform requires the 'win32-open3' package.
+	
+== Ping::HTTP
+Ping::HTTP.new(uri=nil, port=80, timeout=5)
+   Identical to Net::Ping.new except that, instead of a host, the first
+   argument is a URI.
+	
+Ping::HTTP#ping
+   Checks for a response against +uri+.  As long as kind of Net::HTTPSuccess
+   response is returned, the ping is successful and true is returned.
+   Otherwise, false is returned and Ping::HTTP#exception is set to the error
+   message.
+
+   Note that redirects are automatically followed unless the
+   Ping::HTTP#follow_redirects method is set to false.
+
+Ping::HTTP#follow_redirect
+   Indicates whether or not a redirect should be followed in a ping attempt.
+   By default this is set to true.
+
+Ping::HTTP#follow_redirect=(bool)
+   Sets whether or not a redirect should be followed in a ping attempt.  If
+   set to false, then any redirect is considered a failed ping.
+
+Ping::HTTP#uri
+   An alias for Ping::HTTP#host.
+	
+Ping::HTTP#uri=(uri)
+   An alias for Ping::HTTP#host=.
+
+== Ping::ICMP
+Ping::ICMP#duration
+   The time it took to ping the host.  Not a precise value but a good estimate.
+
+== Ping::WMI
+Ping::WMI#ping(host, options={})
+   Unlike other Ping classes, this method returns a PingStatus struct that
+   contains various bits of information about the ping itself. The PingStatus
+   struct is a wrapper for the Win32_PingStatus WMI class.
+
+   In addition, you can pass options that will be interpreted as WQL parameters.
+
+Ping::WMI#ping?(host, options={})
+   Returns whether or not the ping succeeded.
+
+== Ping::LDAP
+Ping::LDAP.new(uri=nil, timeout=5)
+   Performs a 'ping' to an LDAP server in the form of either an anonymous
+   or an authenticated LDAP bind.
+   Identical to Net::Ping.new except that, instead of a host, the first
+   argument is a URI.
+   The default +timeout+ is 5 seconds.
+  
+   +uri+ string is expected to be a full URI with scheme (ldap/ldaps)
+   and optionally the port (else default port is assumed) e.g.
+    ldap://my.ldap.host.com
+    ldap://my.ldap.host.com:1389
+    ldaps://my.ldap.host.com
+    ldaps://my.ldap.host.com:6636
+  
+  If a plain hostname is provided as the +uri+, a default port of 389 is assumed
+
+Ping::LDAP#encryption
+   Set/get the encyption method. By default is nil, but may be set to :simple_tls
+
+Ping::LDAP#username
+Ping::LDAP#password
+   set/get the username and password for ping using and authenticated bind.
+
+= Common Instance Methods
+Ping#exception
+   Returns the error string that was set if a ping call failed.  If an exception
+   is raised, it is caught and stored in this attribute.  It is not raised in
+   your code.
+	
+   This should be nil if the ping succeeded.
+
+Ping#host
+   Returns the host name that ping attempts will ping against.
+
+Ping#host=(hostname)
+   Sets the host name that ping attempts will ping against.
+
+Ping#port
+   Returns the port number that ping attempts will use.
+	
+Ping#port=(port)
+   Set the port number to open socket connections on.  The default is 7 (or
+   whatever your 'echo' port is set to).  Note that you can also specify a
+   string, such as "http".
+
+Ping#timeout
+   Returns the amount of time before the timeout module raises a TimeoutError
+   during connection attempts.  The default is 5 seconds.
+	
+Ping#timeout=(time)
+   Sets the amount of time before the timeout module raises a TimeoutError.
+   during connection attempts.
+	
+Ping#warning
+   Returns a warning string that was returned during the ping attempt.  This
+   typically occurs only in the Ping::External class, or the Ping::HTTP class
+   if a redirect occurred.
+
+== Notes
+   If a host is down *IT IS CONSIDERED A FAILED PING*, and the 'no answer from
+   +host+' text is assigned to the 'exception' attribute.  You may disagree with
+   this behavior, in which case you need merely check the exception attribute
+   against a regex as a simple workaround.
+
+== Pre-emptive FAQ
+   Q: "Why don't you return exceptions if a connection fails?"
+
+   A: Because ping is only meant to return one of two things - success or
+      failure. It's very simple. If you want to find out *why* the ping
+      failed, you can check the 'exception' attribute.
+
+   Q: "I know the host is alive, but a TCP or UDP ping tells me otherwise. What
+      gives?"
+
+   A: It's possible that the echo port has been disabled on the remote
+      host for security reasons. Your best best is to specify a different port
+      or to use Ping::ICMP or Ping::External instead.
+      
+      In the case of UDP pings, they are often actively refused. It may be
+      more pragmatic to set Ping::UDP.service_check = false.
+
+   Q: "Why does a TCP ping return false when I know it should return true?"
+
+   A: By default ECONNREFUSED errors will return a value of false. This is
+      contrary to what most other folks do for TCP pings. The problem with
+      their philosophy is that you can get false positives if a firewall blocks
+      the route to the host. The problem with my philosophy is that you can
+      get false negatives if there is no firewall (or it's not blocking the
+      route). Given the alternatives I chose the latter.
+
+      You can always change the default behavior by using the +service_check+
+      class method.
+      
+      A similar situation is true for UDP pings.
+
+   Q: "Couldn't you use traceroute information to tell for sure?"
+
+   A: I could but I won't so don't bug me about it. It's far more effort than
+      it's worth. If you want something like that, please port the
+      Net::Traceroute Perl module by Daniel Hagerty.
+
+= Known Bugs
+   You may see a test failure from the test_net_ping_tcp test case. You can
+   ignore these.
+   
+   The socket library that ships with the Windows One-Click installer has
+   known issues. This may cause the Ping::ICMP class to fail. In fact, I
+   make an effort to skip those tests if I detect the one-click installer.
+
+   UDP pings may not work with older versions of Ruby 1.9.x.
+
+   Please report any bugs on the project page at
+   http://www.rubyforge.org/projects/shards.
+
+= Acknowledgements
+   The Ping::ICMP#ping method is based largely on the identical method from
+   the Net::Ping Perl module by Rob Brown. Much of the code was ported by
+   Jos Backus on ruby-talk.
+
+= Future Plans
+   Add support for syn pings.
+
+= License
+   Artistic 2.0
+
+= Copyright
+   (C) 2003-2010 Daniel J. Berger, All Rights Reserved
+
+= Warranty
+   This package is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+
+= Author
+   Daniel J. Berger

data/examples/example_pingexternal.rb

@@ -0,0 +1,16 @@
+########################################################################
+# example_pingexternal.rb
+#
+# A short sample program demonstrating an external ping. You can run
+# this program via the example:external task. Modify as you see fit.
+########################################################################
+require 'net/ping'
+
+good = 'www.rubyforge.org'
+bad  = 'foo.bar.baz'
+
+p1 = Net::Ping::External.new(good)
+p p1.ping?
+
+p2 = Net::Ping::External.new(bad)
+p p2.ping?

data/examples/example_pinghttp.rb

@@ -0,0 +1,22 @@
+########################################################################
+# example_pinghttp.rb
+#
+# A short sample program demonstrating an http ping. You can run
+# this program via the example:http task. Modify as you see fit.
+########################################################################
+require 'net/ping'
+
+good = 'http://www.google.com/index.html'
+bad  = 'http://www.ruby-lang.org/index.html'
+
+puts "== Good ping, no redirect"
+
+p1 = Net::Ping::HTTP.new(good)
+p p1.ping?
+
+puts "== Bad ping"
+
+p2 = Net::Ping::HTTP.new(bad)
+p p2.ping?
+p p2.warning
+p p2.exception

data/examples/example_pingtcp.rb

@@ -0,0 +1,16 @@
+########################################################################
+# example_pingtcp.rb
+#
+# A short sample program demonstrating a tcp ping. You can run
+# this program via the example:tcp task. Modify as you see fit.
+########################################################################
+require 'net/ping'
+
+good = 'www.google.com'
+bad  = 'foo.bar.baz'
+
+p1 = Net::Ping::TCP.new(good, 'http')
+p p1.ping?
+
+p2 = Net::Ping::TCP.new(bad)
+p p2.ping?

data/examples/example_pingudp.rb

@@ -0,0 +1,12 @@
+########################################################################
+# example_pingudp.rb
+#
+# A short sample program demonstrating a UDP ping. You can run
+# this program via the example:udp task. Modify as you see fit.
+########################################################################
+require 'net/ping'
+
+host = 'www.google.com'
+
+u = Net::Ping::UDP.new(host)
+p u.ping?

data/lib/net/ping.rb

@@ -0,0 +1,17 @@
+# By doing a "require 'net/ping'" you are requiring every subclass.  If you
+# want to require a specific ping type only, do "require 'net/ping/tcp'",
+# for example.
+#
+require 'rbconfig'
+
+require File.join(File.dirname(__FILE__), 'ping/tcp')
+require File.join(File.dirname(__FILE__), 'ping/udp')
+require File.join(File.dirname(__FILE__), 'ping/icmp')
+require File.join(File.dirname(__FILE__), 'ping/external')
+require File.join(File.dirname(__FILE__), 'ping/http')
+
+RbConfig = Config unless Object.const_defined?(:RbConfig)
+
+if File::ALT_SEPARATOR
+  require File.join(File.dirname(__FILE__), 'ping/wmi')
+end

data/lib/net/ping/external.rb

@@ -0,0 +1,122 @@
+require 'ffi'
+require 'rbconfig'
+
+require File.join(File.dirname(__FILE__), 'ping')
+
+if File::ALT_SEPARATOR && RUBY_VERSION.to_f < 1.9 && RUBY_PLATFORM != 'java'
+  require 'win32/open3'
+else
+  require 'open3'
+end
+
+# The Net module serves as a namespace only.
+module Net
+
+  # The Ping::External class encapsulates methods for external (system) pings.
+  class Ping::External < Ping
+
+    if File::ALT_SEPARATOR
+      extend FFI::Library
+      ffi_lib 'kernel32'
+
+      attach_function :SetConsoleCP, [:uint], :bool
+      attach_function :GetConsoleCP, [], :uint
+    end
+
+    # Pings the host using your system's ping utility and checks for any
+    # errors or warnings. Returns true if successful, or false if not.
+    #
+    # If the ping failed then the Ping::External#exception method should
+    # contain a string indicating what went wrong. If the ping succeeded then
+    # the Ping::External#warning method may or may not contain a value.
+    #
+    def ping(host = @host)
+      super(host)
+
+      stdin = stdout = stderr = nil
+      pstring = "ping "
+      bool    = false
+      orig_cp = nil
+
+      case RbConfig::CONFIG['host_os']
+        when /linux|bsd|osx|mach|darwin/i
+          pstring += "-c 1 #{host}"
+        when /solaris|sunos/i
+          pstring += "#{host} 1"
+        when /hpux/i
+          pstring += "#{host} -n 1"
+        when /win32|windows|msdos|mswin|cygwin|mingw/i
+          orig_cp = GetConsoleCP()
+          SetConsoleCP(437) if orig_cp != 437 # United States
+          pstring += "-n 1 #{host}"
+        else
+          pstring += "#{host}"
+      end
+
+      start_time = Time.now
+
+      begin
+        err = nil
+
+        Timeout.timeout(@timeout){
+          stdin, stdout, stderr = Open3.popen3(pstring)
+          err = stderr.gets # Can't chomp yet, might be nil
+        }
+
+        stdin.close
+        stderr.close
+
+        if File::ALT_SEPARATOR && GetConsoleCP() != orig_cp
+          SetConsoleCP(orig_cp)
+        end
+
+        unless err.nil?
+          if err =~ /warning/i
+            @warning = err.chomp
+            bool = true
+          else
+            @exception = err.chomp
+          end
+        # The "no answer" response goes to stdout, not stderr, so check it
+        else
+          lines = stdout.readlines
+          stdout.close
+          if lines.nil? || lines.empty?
+            bool = true
+          else
+            regexp = /
+              no\ answer|
+              host\ unreachable|
+              could\ not\ find\ host|
+              request\ timed\ out|
+              100%\ packet\ loss
+            /ix
+
+            lines.each{ |line|
+              if regexp.match(line)
+                @exception = line.chomp
+                break
+              end
+            }
+
+            bool = true unless @exception
+          end
+        end
+      rescue Exception => error
+        @exception = error.message
+      ensure
+        stdin.close  if stdin  && !stdin.closed?
+        stdout.close if stdout && !stdout.closed?
+        stderr.close if stderr && !stderr.closed?
+      end
+
+      # There is no duration if the ping failed
+      @duration = Time.now - start_time if bool
+
+      bool
+    end
+
+    alias ping? ping
+    alias pingecho ping
+  end
+end