net-ping 1.3.3-x86-mingw32

data/CHANGES

@@ -0,0 +1,189 @@
+== 1.3.3 - 21-Jun-2010
+* Bug fixes for JRuby on MS Windows. The code now explicitly checks for JRuby
+  in a few places to ensure it doesn't try to load unsupported libraries
+  on MS Windows. Thanks go to Rob Schultz for the spot and some patches.
+* The Net::Ping::HTTP class will no longer fail because a root URI
+  is missing a trailing slash. If the URI#path is empty, it now defaults
+  to the root path.
+* The Rakefile tasks and naming were refactored.
+* Some tests were refactored to take advantage of test-unit 2.x features,
+  as well as make them better and more descriptive in general.
+
+== 1.3.2 - 21-Sep-2009
+* Doing a 'require "net/ping"' was not automatically loading the
+  Net::Ping::WMI class on MS Windows. This has been fixed. Thanks go to
+  Joseph M. for the spot. 
+* Removed all $LOAD_PATH mangling for both the library and tests.
+* Fixed a bug in the Net::Ping::HTTP class where a failed redirect did
+  not set the @exception and @warning instance variables properly.
+* The PingStatus struct returned by Net::Ping::WMI is now frozen.
+* The test-unit library was switched from a runtime dependency to a
+  development dependency.
+* Added the :gem Rake task that builds a gem.
+* Updated the :gem_install task to use the :gem task as a prerequisite.
+* Updated the dependencies for MS Windows.
+* The Rake test tasks are now more Rakish, e.g. test:tcp instead of test_tcp.
+* Renamed example file names to avoid any potential confusion with actual
+  test files.
+
+== 1.3.1 - 22-Jul-2009
+* Removed class aliases, e.g. use Ping::External, not PingExternal.
+* Minor code change to eliminate a warning that popped up in 1.9.x.
+* The win32-open3 library is removed as a dependency for Ruby 1.9.x.
+* Changed license to Artistic 2.0.
+* Some gemspec and README updates.
+
+== 1.3.0 - 19-May-2009
+* Added the Ping::WMI class for MS Windows. This class encapsulates the
+  Win32_PingStatus WMI class. Unlike other ping methods, this one returns
+  a struct that contains various bits of information.
+* The Net::Ping::External class now ensures that handles opened by the open3
+  call are closed. Thanks go to Nick S. Kanakakorn for the spot and a
+  preliminary patch.
+* The Net::Ping::ICMP class now explicitly closes the socket if the call to
+  the Socket.pack_sockaddr_in method fails.
+* Some documentation updates.
+
+== 1.2.3 - 13-Jan-2008
+* Fixed a bug in the checksum private method where it would die on odd data
+  sizes. Thanks go to Jake Douglas for the spot.
+* A Socket.get_sockaddr_in call in the Ping::ICMP class is no longer included
+  as part of the overall ping time. Thanks go again to Jake Douglas for
+  the spot.
+* Added data_size tests to the Ping::ICMP test suite.
+* Renamed and updated the test files. The test-unit 2.x gem is now a
+  prerequisite as a result.
+
+== 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,23 @@
+* MANIFEST
+* CHANGES
+* Rakefile
+* README
+* net-ping.gemspec
+* examples/example_pingexternal.rb
+* examples/example_pinghttp.rb
+* examples/example_pingtcp.rb
+* examples/example_pingudp.rb
+* lib/net/ping.rb
+* lib/net/ping/icmp.rb
+* lib/net/ping/tcp.rb
+* lib/net/ping/udp.rb
+* lib/net/ping/wmi.rb
+* lib/net/ping/http.rb
+* lib/net/ping/external.rb
+* test/test_net_ping_external.rb
+* test/test_net_ping_http.rb
+* test/test_net_ping_icmp.rb
+* test/test_net_ping_tcp.rb
+* test/test_net_ping_udp.rb
+* test/test_net_ping_wmi.rb
+* test/test_net_ping.rb

data/README

@@ -0,0 +1,48 @@
+== Description
+   A collection of classes that provide different ways to ping computers.
+
+== Prerequisites
+   * Ruby 1.8.0 or later
+   * The win32-open3 (1.8.x) and windows-pr libraries are required on
+     MS Windows when using the Net::Ping::External class unless you're
+     using JRuby.
+   * Windows 2000 or later is required to use the Ping::WMI class.
+
+== Installation
+   gem install net-ping
+
+== 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.
+   
+   You do not need win32-open3 with Ruby 1.9.x. The open3 library that ships
+   as part of the Ruby standard library should work.
+
+== 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.
+   
+== Known Issues
+   Older versions of Ruby 1.9.x may not work with UDP pings.
+   As of JRuby 1.5.1, UDP pings will return false positives because of an
+   incorrect error class being raised. See JRuby-4896.
+
+== License
+   Artistic 2.0
+   
+== More documentation
+   If you installed this library via Rubygems, you can view the inline
+   documentation via ri or fire up 'gem server', and point your browser at
+   http://localhost:8808.

data/Rakefile

@@ -0,0 +1,84 @@
+require 'rake'
+require 'rake/testtask'
+include Config
+
+namespace 'gem' do
+  desc 'Create the net-ping gem'
+  task :create do
+    spec = eval(IO.read('net-ping.gemspec'))
+    Gem::Builder.new(spec).build
+  end
+
+  desc 'Install the net-ping gem'
+  task :install => [:create] do
+    gem_file = Dir["*.gem"].first
+    sh "gem install #{gem_file}"
+  end
+end
+
+namespace 'example' do
+  desc 'Run the external ping example program'
+  task :external do
+     ruby '-Ilib examples/example_pingexternal.rb'
+  end
+
+  desc 'Run the http ping example program'
+  task :http do
+     ruby '-Ilib examples/example_pinghttp.rb'
+  end
+
+  desc 'Run the tcp ping example program'
+  task :tcp do
+     ruby '-Ilib examples/example_pingtcp.rb'
+  end
+
+  desc 'Run the udp ping example program'
+  task :udp do
+     ruby '-Ilib examples/example_pingudp.rb'
+  end
+end
+
+Rake::TestTask.new do |t|
+   t.libs << 'test'
+   t.warning = true
+   t.verbose = true
+   t.test_files = FileList['test/test_net_ping.rb']
+end
+
+namespace 'test' do
+  Rake::TestTask.new('external') do |t|
+     t.warning = true
+     t.verbose = true
+     t.test_files = FileList['test/test_net_ping_external.rb']
+  end
+
+  Rake::TestTask.new('http') do |t|
+     t.warning = true
+     t.verbose = true
+     t.test_files = FileList['test/test_net_ping_http.rb']
+  end
+
+  Rake::TestTask.new('icmp') do |t|
+     t.warning = true
+     t.verbose = true
+     t.test_files = FileList['test/test_net_ping_icmp.rb']
+  end
+
+  Rake::TestTask.new('tcp') do |t|
+     t.warning = true
+     t.verbose = true
+     t.test_files = FileList['test/test_net_ping_tcp.rb']
+  end
+
+  Rake::TestTask.new('udp') do |t|
+     t.warning = true
+     t.verbose = true
+     t.test_files = FileList['test/test_net_ping_udp.rb']
+  end
+
+  Rake::TestTask.new('wmi') do |t|
+     t.warning = true
+     t.verbose = true
+     t.test_files = FileList['test/test_net_ping_wmi.rb']
+  end
+end

data/doc/ping.txt

@@ -0,0 +1,249 @@
+= 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
+
+   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.
+
+= 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