NAME
   LWP::Online - Does your process have access to the web

SYNOPSIS
     use LWP::Online 'online';

     # "Is the internet working?"
     die "NO INTARWWEB!!!" unless online();

     # The above means something like this
     unless ( online('http') ) {
         die "No basic http access to the web";
     }

     # Special syntax for use in test scripts that need
     # "real" access to the internet. Scripts will automatically
     # skip if connection fails.
     use LWP::Online ':skip_all';

DESCRIPTION
   This module attempts to answer, as accurately as it can, one of the
   nastiest technical questions there is.

   Am I on the internet?

   The answer is useful in a wide range of decisions. For example...

   *Should my test scripts run the online portion of the tests or just skip
   them?*

   *Do I try to fetch fresh data from the server?*

   *If my request to the server breaks, is it because I'm offline, or
   because the server is offline?*

   And so on, and so forth.

   But a host of networking and security issues make this problem very
   difficult. There are firewalls, proxies (both well behaved and badly
   behaved). We might not have DNS. We might not have a network card at
   all!

   You might have network access, but only to a for-money wireless network
   that responds to ever HTTP request with a page asking you to enter your
   credit card details for paid access. Which means you don't "REALLY" have
   access.

   The mere nature of the question makes it practically unsolvable.

   But with the answer being so useful, and the only other alternative
   being to ask the user "duh... are you online?" (when you might not have
   a user at all) it's my gut feeling that it is worthwhile at least making
   an attempt to solve the problem, if only in a limited way.

 Why LWP::Online? Why not Net::Online?
   The nice thing about LWP::Online is that LWP deals with a whole range of
   different transports, and is very commonly installed. HTTP, HTTPS, FTP,
   and so on and so forth.

   Attempting to do a more generalised Net::Online that might also check
   for SSH and so on would end up most likely having to install a whole
   bunch of modules that you most likely will never use.

   So LWP forms a nice base on which to write a module that covers most of
   the situations in which you might care, while keeping the dependency
   overhead down to a minimum.

 Scope
   "Am I online?" is inherently an Open Problem.

   That is, it's a problem that had no clean permanent solution, and for
   which you could just keep writing more and more functionality
   indefinitely, asymtopically approaching 100% correctness but never
   reaching it.

   And so this module is intended to do as good a job as possible, without
   having to resort to asking any human questions (who may well get it
   wrong anyway), and limiting itself to a finite amount of programming
   work and a reasonable level of memory overhead to load the code.

   It is thus understood the module will never be perfect, and that if any
   new functionality is desired, it needs to be able to implemented by the
   person that desires the new behaviour, and in a reasonably small amount
   of additional code.

   This module is also not intended to compensate for malicious behaviour
   of any kind, it is quite possible that some malicious person might proxy
   fake versions of sites that pass our content checks and then proceed to
   show you other bad pages.

 Test Mode
     use LWP::Online ':skip_all';

   As a convenience when writing tests scripts base on Test::More, the
   special ':skip_all' param can be provided when loading LWP::Online.

   This implements the functional equivalent of the following.

     BEGIN {
       require Test::More;
       unless ( LWP::Online::online() ) {
         Test::More->import(
           skip_all => 'Test requires a working internet connection'
         );
       }
     }

   The :skip_all special import flag can be mixed with regular imports.

FUNCTIONS
 online
     # Default check (uses http)
     online() or die "No Internet";

     # The above is equivalent to
     online('http') or die "No Internet";

   The importable online function is the main functionality provided by
   LWP::Online. It takes a single optional transport name ('http' by
   default) and checks that LWP connectivity is available for that
   transport.

   Because it is intended as a Do What You Mean function, it checks not
   only that a network connection is available, and http requests return
   content, but also that it returns the CORRECT content instead of
   unexpected content supplied by a man in the middle.

   For example, many wireless connections require login or payment, and
   will return a service provider page for any URI that you attempt to
   fetch.

   The set of websites used for the testing is the Google, Amazon, Yahoo
   and CNN websites. The check is for a copyright statement on their
   homepage, and the function returns true as soon as two of the website
   return correctly, making the method relatively redundant.

   Returns true if the computer is "online" (has a working connection via
   LWP) or false if not.

 offline
   The importable offline function is provided as a convenience.

   It provides a simple pass-through (including any params) to the online
   function, but with a negated result.

TO DO
   - Add more transport types that can be checked, somehow keeping the code
   growth under control.

SUPPORT
   This module is stored in an Open Repository at the following address.

   <http://svn.ali.as/cpan/trunk/LWP-Online>

   Write access to the repository is made available automatically to any
   published CPAN author, and to most other volunteers on request.

   If you are able to submit your bug report in the form of new (failing)
   unit tests (which for this module will be extremely difficult), or can
   apply your fix directly instead of submitting a patch, you are strongly
   encouraged to do so as the author currently maintains over 100 modules
   and it can take some time to deal with non-Critical bug reports or
   patches.

   This will guarentee that your issue will be addressed in the next
   release of the module.

   If you cannot provide a direct test or fix, or don't have time to do so,
   then regular bug reports are still accepted and appreciated via the CPAN
   bug tracker.

   <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LWP-Online>

   For other issues, for commercial enhancement or support, or to have your
   write access enabled for the repository, contact the author at the email
   address above.

AUTHOR
   Adam Kennedy <[email protected]>

SEE ALSO
   LWP::Simple

COPYRIGHT
   Copyright 2006 - 2008 Adam Kennedy.

   This program is free software; you can redistribute it and/or modify it
   under the same terms as Perl itself.

   The full text of the license can be found in the LICENSE file included
   with this module.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.