1LWP::Online(3) User Contributed Perl Documentation LWP::Online(3)
2
6 LWP::Online - Does your process have access to the web
7
9 use LWP::Online 'online';
10 # "Is the internet working?"
12 die "NO INTARWWEB!!!" unless online();
13 # The above means something like this
15 unless ( online('http') ) {
16 die "No basic http access to the web";
17 }
18 # 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
25 This module attempts to answer, as accurately as it can, one of the
26 nastiest technical questions there is.
27 Am I on the internet?
29 The answer is useful in a wide range of decisions. For example...
31 Should my test scripts run the online portion of the tests or just skip
33 them?
34 Do I try to fetch fresh data from the server?
36 If my request to the server breaks, is it because I'm offline, or
38 because the server is offline?
39 And so on, and so forth.
41 But a host of networking and security issues make this problem very
43 difficult. There are firewalls, proxies (both well behaved and badly
44 behaved). We might not have DNS. We might not have a network card at
45 all!
46 You might have network access, but only to a for-money wireless network
48 that responds to ever HTTP request with a page asking you to enter your
49 credit card details for paid access. Which means you don't "REALLY"
50 have access.
51 The mere nature of the question makes it practically unsolvable.
53 But with the answer being so useful, and the only other alternative
55 being to ask the user "duh... are you online?" (when you might not have
56 a user at all) it's my gut feeling that it is worthwhile at least
57 making an attempt to solve the problem, if only in a limited way.
58 Why LWP::Online? Why not Net::Online?
60 The nice thing about LWP::Online is that LWP deals with a whole range
61 of different transports, and is very commonly installed. HTTP, HTTPS,
62 FTP, and so on and so forth.
63 Attempting to do a more generalised Net::Online that might also check
65 for SSH and so on would end up most likely having to install a whole
66 bunch of modules that you most likely will never use.
67 So LWP forms a nice base on which to write a module that covers most of
69 the situations in which you might care, while keeping the dependency
70 overhead down to a minimum.
71 Scope
73 "Am I online?" is inherently an Open Problem.
74 That is, it's a problem that had no clean permanent solution, and for
76 which you could just keep writing more and more functionality
77 indefinitely, asymtopically approaching 100% correctness but never
78 reaching it.
79 And so this module is intended to do as good a job as possible, without
81 having to resort to asking any human questions (who may well get it
82 wrong anyway), and limiting itself to a finite amount of programming
83 work and a reasonable level of memory overhead to load the code.
84 It is thus understood the module will never be perfect, and that if any
86 new functionality is desired, it needs to be able to implemented by the
87 person that desires the new behaviour, and in a reasonably small amount
88 of additional code.
89 This module is also not intended to compensate for malicious behaviour
91 of any kind, it is quite possible that some malicious person might
92 proxy fake versions of sites that pass our content checks and then
93 proceed to show you other bad pages.
94 Test Mode
96 use LWP::Online ':skip_all';
97 As a convenience when writing tests scripts base on Test::More, the
99 special ':skip_all' param can be provided when loading LWP::Online.
100 This implements the functional equivalent of the following.
102 BEGIN {
104 require Test::More;
105 unless ( LWP::Online::online() ) {
106 Test::More->import(
107 skip_all => 'Test requires a working internet connection'
108 );
109 }
110 }
111 The :skip_all special import flag can be mixed with regular imports.
113
115 online
116 # Default check (uses http)
117 online() or die "No Internet";
118 # The above is equivalent to
120 online('http') or die "No Internet";
121 The importable online function is the main functionality provided by
123 LWP::Online. It takes a single optional transport name ('http' by
124 default) and checks that LWP connectivity is available for that
125 transport.
126 Because it is intended as a Do What You Mean function, it checks not
128 only that a network connection is available, and http requests return
129 content, but also that it returns the CORRECT content instead of
130 unexpected content supplied by a man in the middle.
131 For example, many wireless connections require login or payment, and
133 will return a service provider page for any URI that you attempt to
134 fetch.
135 The set of websites used for the testing is the Google, Amazon, Yahoo
137 and CNN websites. The check is for a copyright statement on their
138 homepage, and the function returns true as soon as two of the website
139 return correctly, making the method relatively redundant.
140 Returns true if the computer is "online" (has a working connection via
142 LWP) or false if not.
143 offline
145 The importable offline function is provided as a convenience.
146 It provides a simple pass-through (including any params) to the online
148 function, but with a negated result.
149
151 - Add more transport types that can be checked, somehow keeping the
152 code growth under control.
153
155 This module is stored in an Open Repository at the following address.
156 http://svn.ali.as/cpan/trunk/LWP-Online
158 <http://svn.ali.as/cpan/trunk/LWP-Online>
159 Write access to the repository is made available automatically to any
161 published CPAN author, and to most other volunteers on request.
162 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 This will guarentee that your issue will be addressed in the next
171 release of the module.
172 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 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LWP-Online
178 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=LWP-Online>
179 For other issues, for commercial enhancement or support, or to have
181 your write access enabled for the repository, contact the author at the
182 email address above.
183
185 Adam Kennedy <adamk@cpan.org>
186
188 LWP::Simple
189
191 Copyright 2006 - 2008 Adam Kennedy.
192 This program is free software; you can redistribute it and/or modify it
194 under the same terms as Perl itself.
195 The full text of the license can be found in the LICENSE file included
197 with this module.
198perl v5.12.0 2008-07-07 LWP::Online(3)