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';
         use Test::More tests => 4; #after LWP::Online

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 <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
       <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 <adamk@cpan.org>

SEE ALSO

       LWP::Simple

COPYRIGHT

       Copyright 2006 - 2011 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.