net-ping 1.4.1-x86-mingw32 → 1.5.3-x86-mingw32

data/MANIFEST

@@ -1,23 +1,25 @@
-* 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
+* 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/ldap.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_ldap.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

@@ -1,46 +1,52 @@
-== Description
-   A collection of classes that provide different ways to ping computers.
-
-== Prerequisites
-   * 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.
-
-== 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.
-   Older versions of JRuby will return false positives in UDP pings
-   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.
+== Description
+   A collection of classes that provide different ways to ping computers.
+
+== Prerequisites
+   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.
+
+   JRuby users should use 1.6.7 or later.
+
+== 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.
+
+   Older versions of JRuby will return false positives in UDP pings
+   because of an incorrect error class being raised. See JRuby-4896.
+
+   JRuby 1.6.7 or later is required for external pings because of a bug
+   in earlier versions with open3 and stream handling.
+
+== 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

@@ -1,89 +1,100 @@
-require 'rake'
-require 'rake/clean'
-require 'rake/testtask'
-include Config
-
-CLEAN.include("**/*.gem", "**/*.rbc")
-
-namespace 'gem' do
-  desc 'Create the net-ping gem'
-  task :create => [:clean] 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
-
-task :default => :test
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+include Object.const_defined?(:RbConfig) ? RbConfig : Config
+
+CLEAN.include("**/*.gem", "**/*.rbc")
+
+namespace 'gem' do
+  desc 'Create the net-ping gem'
+  task :create => [:clean] 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
+
+  desc 'Run the ldap ping example program'
+  task :ldap do
+     ruby '-Ilib examples/example_pingldap.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
+
+  Rake::TestTask.new('ldap') do |t|
+     t.warning = true
+     t.verbose = true
+     t.test_files = FileList['test/test_net_ping_ldap.rb']
+  end
+end
+
+task :default => :test

data/doc/ping.txt

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