net-ping 1.2.2-x86-mswin32-60

data/CHANGES

@@ -0,0 +1,133 @@
+== 1.2.2 - 22-Jan-2008
+* Bug fix for Ping::External where it was not honoring the timeout value.
+  Thanks go to Chris Morris for the spot and the patch.
+* Bug fix for Ping::External where non-English output could cause false
+  positives on MS Windows Vista or later. This library now requires the
+  windows-pr library on MS Windows systems as a result.
+* Added the Ping::UDP.service_check and Ping::UDP.service_check= class
+  methods. This method controls whether or not Errno::ECONNREFUSED or
+  Errno::ECONNRESET are considered successful pings or not.
+* The Ping::HTTP class no longer uses the resolv-replace library on MS Windows
+  because it was (ironically) causing timeouts.
+* Changed the Ping::TCP.econnrefused method to Ping::TCP.service_check. I
+  changed it because I now use a similar method in Ping::UDP, but that handles
+  more than Errno::ECONNREFUSED. An alias is provided to provide backwards
+  compatibility, but it is considered deprecated and will be removed in the
+  1.3.0 release.
+* Removed the install.rb file. The Rakefile now handles installation.
+
+== 1.2.1 - 6-Apr-2007
+* For the Ping::External class, if a ping attempt results in 100% packet loss
+  it is now considered a failed ping, regardless of whether or not an error
+  was sent to stdout.
+* Fixed the Ping::External class for OS X.
+* Added a Rakefile. Installation and testing should now be run via Rake tasks.
+* Minor fix for the Ping::ICMP class where I had accidentally dup'd some
+  aliases. This was harmless, but did cause warnings with -w.
+
+== 1.2.0 - 5-Dec-2006
+* Internal reorganization - each class now lives in its own file.
+* Added the Ping::ICMP class.  Thanks go to Jos Backus for contributing a 
+  large part of the code.
+* The host argument is now optional in the constructor.  You can now specify
+  it in the ping method instead.  Note that it must be specified in one place
+  or the other.
+* Each PingXXX class is now Ping::XXX instead.  However, class name aliases
+  have been setup for backwards compatibility for now.
+* The constructor for each Ping types now yields self.
+* Added the pingecho alias for the ping method for each Ping type.
+* Added the Ping::HTTP#follow_redirect accessor.
+* The Ping::HTTP#ping method now honors the timeout value.
+* The Ping::HTTP class now follows redirects automatically, though this is
+  configurable with the follow_redirect accessor.
+* The Ping::TCP.ecr and Ping::TCP.ecr= methods are now true class method
+  aliases (they were just wrappers previously).
+* The Ping::UDP class now enforces a 64 character limit on data that can be
+  sent on a udp ping.
+* Updated the gemspec.  Specifically, MS Windows now has a dependency on
+  the win32-open3 package.
+* Added inline rdoc.
+
+== 1.1.1 - 15-Jun-2006
+* Fixed a bug in PingTCP (bad variable name).  Thanks go to Anoop Chandran
+  for the spot.
+* Minor variable name refactoring.
+* Minor test updates.
+
+== 1.1.0 - 17-Jul-2005
+* Fixed a bug in the PingHTTP#ping method where I was accidentally passing
+  the timeout value instead of the port number as the third argument to
+  Net::HTTP.get_response.
+* The PingHTTP.new method now has a default port of 80.
+* Minor doc update for PingHTTP.new.
+
+== 1.0.1 - 22-Jun-2005
+* Bug fix for the install.rb file.  The gem is unaffected.
+
+== 1.0.0 - 14-Jun-2005
+* Renamed project from net-pingsimple to just net-ping.
+* Added a PingHTTP subclass.
+* Moved project to RubyForge.
+* Added a gemspec.
+
+== 0.3.1 - 9-Apr-2005
+* Updated PingExternal to use win32/open3 on Win32 platforms.
+* Minor error handling change for the PingSimple.econnrefused= method.  It now
+  raises an ArgumentError if any values other than true or false are passed.
+* PingSimple#warning and PingSimple#exception are now read-only methods.
+* The warning and exception attributes are now reset to nil between each call
+  to ping.
+* The data and data= methods are now unique to the PingUDP class.
+* The time and time= methods have been changed to timeout and timeout=,
+  respectively.
+* Removed the pingsimple.rd and pingsimple.html files.  The pingsimple.txt file
+  has been reorganized and is now rdoc friendly.
+* Added a few sample programs under the 'examples' directory.
+* Some minor test updates and changes.
+* Removed the INSTALL file.  That information is now in the README file.
+* Now requires Ruby 1.8.0 or later.
+
+== 0.3.0 - 12-Feb-2004
+* Fixed ping string for PingExternal class based on platform.  The old
+  string was really only good for Linux and *BSD.
+* Added Win32 support (requires win32_popen package).
+* Added warranty info.
+
+== 0.2.3 - 12-Aug-2003
+* Fixed a bug in PingExternal that could consume file descriptors if used in a loop
+* Added some initialization to avoid -w warnings
+* Removed VERSION() class method.  Use the constant instead
+* Modified test suite slightly
+* Moved rd2 docs to doc directory
+
+== 0.2.2 - 3-Apr-2003
+* Fixed handling of stdout in PingExternal
+
+== 0.2.1 - 27-Mar-2003
+* Fixed major bug with PingExternal class with regards to down hosts
+* Exceptions and warnings from PingExternal are now chomp'd
+* Modified test suite
+* Doc updates
+
+== 0.2.0 - 14-Feb-2003
+* The default behavior of PingTCP with regards to ECONNREFUSED is now 
+  configurable
+* Added a VERSION constant and method (to the base class)
+* Added a test suite (for those with testunit installed)
+* Doc changes, rearrangement and general cleanup
+* Manifest is now MANIFEST
+* Added an INSTALL file
+
+== 0.1.0 - 9-Dec-2002
+* Added ping? alias for ping method
+* Warnings now handled separately
+* Corrected a mis-named variable in Ping::External
+* Fixed the install.rb file
+* Updated and added docs
+* Renamed tarball to net-pingsimple to reflect RAA naming convention
+
+== 0.0.1a
+* Did this release ever happen?
+
+== 0.0.1
+* Initial release.

data/MANIFEST

@@ -0,0 +1,21 @@
+* MANIFEST
+* CHANGES
+* Rakefile
+* README
+* net-ping.gemspec
+* examples/test_pingexternal.rb
+* examples/test_pinghttp.rb
+* examples/test_pingtcp.rb
+* examples/test_pingudp.rb
+* lib/net/ping.rb
+* lib/net/ping/icmp.rb
+* lib/net/ping/tcp.rb
+* lib/net/ping/udp.rb
+* lib/net/ping/http.rb
+* lib/net/ping/external.rb
+* test/tc_pingexternal.rb
+* test/tc_pinghttp.rb
+* test/tc_pingicmp.rb
+* test/tc_pingtcp.rb
+* test/tc_pingudp.rb
+* test/ts_ping.rb

data/README

@@ -0,0 +1,31 @@
+== Description
+   A collection of classes that provide different ways to ping computers.
+
+== Prerequisites
+   * Ruby 1.8.0 or later
+   * The win32-open3 and windows-pr libraries are required on MS Windows
+   when using the Net::Ping::External class.
+
+== Installation
+   rake test (optional)
+   rake install (standard) OR rake gem_install (gems)
+
+== Notes
+   Please read the documentation under the 'doc' directory. Especially pay
+   attention to the documentation pertaining to ECONNREFUSED and TCP pings.
+
+   Also note the documentation regarding down hosts.
+
+== How to require net-ping
+   You can do either this:
+
+   require 'net/ping'
+
+   In which case you will get Net::Ping and all of its subclasses. Or,
+   you can load individual subclasses like this:
+
+   require 'net/ping/tcp'
+
+   The former has the advantage of being easier to remember and all inclusive,
+   not to mention backwards compatible. The latter has the advantage of
+   reducing your memory footprint.

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rake'
+require 'rake/testtask'
+include Config
+
+desc "Install the net-ping package (non-gem)"
+task :install do
+   dest1 = File.join(CONFIG['sitelibdir'], 'net')
+   dest2 = File.join(dest1, 'ping')
+
+   Dir.mkdir(dest1) unless File.exists?(dest1)
+   Dir.mkdir(dest2) unless File.exists?(dest2)
+
+   FileUtils.cp('lib/net/ping.rb', dest1, :verbose => true)
+
+   Dir['lib/net/ping/*.rb'].each{ |file|
+      FileUtils.cp(file, dest2, :verbose => true)
+   }
+end
+
+desc "Create and install a net-ping gem"
+task :gem_install do
+   ruby 'net-ping.gemspec'
+   gem_file = Dir["*.gem"].first
+   sh "gem install #{gem_file}"
+end
+
+Rake::TestTask.new("test") do |t|
+   t.warning = true
+   t.test_files = FileList['test/ts_ping.rb']
+end
+
+Rake::TestTask.new("test_external") do |t|
+   t.warning = true
+   t.test_files = FileList['test/tc_pingexternal.rb']
+end
+
+Rake::TestTask.new("test_http") do |t|
+   t.warning = true
+   t.test_files = FileList['test/tc_pinghttp.rb']
+end
+
+Rake::TestTask.new("test_icmp") do |t|
+   t.warning = true
+   t.test_files = FileList['test/tc_pingicmp.rb']
+end
+
+Rake::TestTask.new("test_tcp") do |t|
+   t.warning = true
+   t.test_files = FileList['test/tc_pingtcp.rb']
+end
+
+Rake::TestTask.new("test_udp") do |t|
+   t.warning = true
+   t.test_files = FileList['test/tc_pingudp.rb']
+end

data/doc/ping.txt

@@ -0,0 +1,231 @@
+= Description
+   A simple Ruby interface to the 'ping' command.
+
+= Synopsis
+   require "net/ping"
+   include Net
+
+   Ping::TCP.econnrefused = 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
+
+   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.
+
+== 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.
+
+= 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 tc_pingtcp test case. You can ignore
+   this.
+
+   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
+   Ruby's
+
+= Copyright
+   (C) 2003-2008 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
+   djberg96 at gmail dot com
+   imperator on IRC (irc.freenode.net)