1LWP::Online(3)        User Contributed Perl Documentation       LWP::Online(3)
2
3
4

NAME

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

SYNOPSIS

9         use LWP::Online 'online';
10
11         # "Is the internet working?"
12         die "NO INTARWWEB!!!" unless online();
13
14         # The above means something like this
15         unless ( online('http') ) {
16             die "No basic http access to the web";
17         }
18
19         # Special syntax for use in test scripts that need
20         # "real" access to the internet. Scripts will automatically
21         # skip if connection fails.
22         use LWP::Online ':skip_all';
23         use Test::More tests => 4; #after LWP::Online
24

DESCRIPTION

26       This module attempts to answer, as accurately as it can, one of the
27       nastiest technical questions there is.
28
29       Am I on the internet?
30
31       The answer is useful in a wide range of decisions. For example...
32
33       Should my test scripts run the online portion of the tests or just skip
34       them?
35
36       Do I try to fetch fresh data from the server?
37
38       If my request to the server breaks, is it because I'm offline, or
39       because the server is offline?
40
41       And so on, and so forth.
42
43       But a host of networking and security issues make this problem very
44       difficult. There are firewalls, proxies (both well behaved and badly
45       behaved). We might not have DNS. We might not have a network card at
46       all!
47
48       You might have network access, but only to a for-money wireless network
49       that responds to ever HTTP request with a page asking you to enter your
50       credit card details for paid access. Which means you don't "REALLY"
51       have access.
52
53       The mere nature of the question makes it practically unsolvable.
54
55       But with the answer being so useful, and the only other alternative
56       being to ask the user "duh... are you online?" (when you might not have
57       a user at all) it's my gut feeling that it is worthwhile at least
58       making an attempt to solve the problem, if only in a limited way.
59
60   Why LWP::Online? Why not Net::Online?
61       The nice thing about LWP::Online is that LWP deals with a whole range
62       of different transports, and is very commonly installed. HTTP, HTTPS,
63       FTP, and so on and so forth.
64
65       Attempting to do a more generalised Net::Online that might also check
66       for SSH and so on would end up most likely having to install a whole
67       bunch of modules that you most likely will never use.
68
69       So LWP forms a nice base on which to write a module that covers most of
70       the situations in which you might care, while keeping the dependency
71       overhead down to a minimum.
72
73   Scope
74       "Am I online?" is inherently an Open Problem.
75
76       That is, it's a problem that had no clean permanent solution, and for
77       which you could just keep writing more and more functionality
78       indefinitely, asymtopically approaching 100% correctness but never
79       reaching it.
80
81       And so this module is intended to do as good a job as possible, without
82       having to resort to asking any human questions (who may well get it
83       wrong anyway), and limiting itself to a finite amount of programming
84       work and a reasonable level of memory overhead to load the code.
85
86       It is thus understood the module will never be perfect, and that if any
87       new functionality is desired, it needs to be able to implemented by the
88       person that desires the new behaviour, and in a reasonably small amount
89       of additional code.
90
91       This module is also not intended to compensate for malicious behaviour
92       of any kind, it is quite possible that some malicious person might
93       proxy fake versions of sites that pass our content checks and then
94       proceed to show you other bad pages.
95
96   Test Mode
97         use LWP::Online ':skip_all';
98
99       As a convenience when writing tests scripts base on Test::More, the
100       special ':skip_all' param can be provided when loading LWP::Online.
101
102       This implements the functional equivalent of the following.
103
104         BEGIN {
105           require Test::More;
106           unless ( LWP::Online::online() ) {
107             Test::More->import(
108               skip_all => 'Test requires a working internet connection'
109             );
110           }
111         }
112
113       The :skip_all special import flag can be mixed with regular imports.
114

FUNCTIONS

116   online
117         # Default check (uses http)
118         online() or die "No Internet";
119
120         # The above is equivalent to
121         online('http') or die "No Internet";
122
123       The importable online function is the main functionality provided by
124       LWP::Online. It takes a single optional transport name ('http' by
125       default) and checks that LWP connectivity is available for that
126       transport.
127
128       Because it is intended as a Do What You Mean function, it checks not
129       only that a network connection is available, and http requests return
130       content, but also that it returns the CORRECT content instead of
131       unexpected content supplied by a man in the middle.
132
133       For example, many wireless connections require login or payment, and
134       will return a service provider page for any URI that you attempt to
135       fetch.
136
137       The set of websites used for the testing is the Google, Amazon, Yahoo
138       and CNN websites. The check is for a copyright statement on their
139       homepage, and the function returns true as soon as two of the website
140       return correctly, making the method relatively redundant.
141
142       Returns true if the computer is "online" (has a working connection via
143       LWP) or false if not.
144
145   offline
146       The importable offline function is provided as a convenience.
147
148       It provides a simple pass-through (including any params) to the online
149       function, but with a negated result.
150

TO DO

152       - Add more transport types that can be checked, somehow keeping the
153       code growth under control.
154

SUPPORT

156       This module is stored in an Open Repository at the following address.
157
158       <http://svn.ali.as/cpan/trunk/LWP-Online>
159
160       Write access to the repository is made available automatically to any
161       published CPAN author, and to most other volunteers on request.
162
163       If you are able to submit your bug report in the form of new (failing)
164       unit tests (which for this module will be extremely difficult), or can
165       apply your fix directly instead of submitting a patch, you are strongly
166       encouraged to do so as the author currently maintains over 100 modules
167       and it can take some time to deal with non-Critical bug reports or
168       patches.
169
170       This will guarentee that your issue will be addressed in the next
171       release of the module.
172
173       If you cannot provide a direct test or fix, or don't have time to do
174       so, then regular bug reports are still accepted and appreciated via the
175       CPAN bug tracker.
176
177       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LWP-Online>
178
179       For other issues, for commercial enhancement or support, or to have
180       your write access enabled for the repository, contact the author at the
181       email address above.
182

AUTHOR

184       Adam Kennedy <adamk@cpan.org>
185

SEE ALSO

187       LWP::Simple
188
190       Copyright 2006 - 2011 Adam Kennedy.
191
192       This program is free software; you can redistribute it and/or modify it
193       under the same terms as Perl itself.
194
195       The full text of the license can be found in the LICENSE file included
196       with this module.
197
198
199
200perl v5.28.0                      2011-07-08                    LWP::Online(3)
Impressum