231 lines
5.2 KiB
HTML
231 lines
5.2 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of LWP::Protocol</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>LWP::Protocol</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2019-11-29<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
LWP::Protocol - Base class for LWP protocols
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
package LWP::Protocol::foo;
|
|
use base qw(LWP::Protocol);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
This class is used as the base class for all protocol implementations
|
|
supported by the <FONT SIZE="-1">LWP</FONT> library.
|
|
<P>
|
|
|
|
When creating an instance of this class using
|
|
<TT>"LWP::Protocol::create($url)"</TT>, and you get an initialized subclass
|
|
appropriate for that access method. In other words, the
|
|
``create'' in LWP::Protocol function calls the constructor for one of its
|
|
subclasses.
|
|
<P>
|
|
|
|
All derived <TT>"LWP::Protocol"</TT> classes need to override the <B>request()</B>
|
|
method which is used to service a request. The overridden method can
|
|
make use of the <B>collect()</B> function to collect together chunks of data
|
|
as it is received.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>METHODS</H2>
|
|
|
|
|
|
|
|
The following methods and functions are provided:
|
|
<A NAME="lbAF"> </A>
|
|
<H3>new</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $prot = LWP::Protocol->new();
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The LWP::Protocol constructor is inherited by subclasses. As this is a
|
|
virtual base class this method should <B>not</B> be called directly.
|
|
<A NAME="lbAG"> </A>
|
|
<H3>create</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $prot = LWP::Protocol::create($scheme)
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Create an object of the class implementing the protocol to handle the
|
|
given scheme. This is a function, not a method. It is more an object
|
|
factory than a constructor. This is the function user agents should
|
|
use to access protocols.
|
|
<A NAME="lbAH"> </A>
|
|
<H3>implementor</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $class = LWP::Protocol::implementor($scheme, [$class])
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Get and/or set implementor class for a scheme. Returns <TT>''</TT> if the
|
|
specified scheme is not supported.
|
|
<A NAME="lbAI"> </A>
|
|
<H3>request</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$response = $protocol->request($request, $proxy, undef);
|
|
$response = $protocol->request($request, $proxy, '/tmp/sss');
|
|
$response = $protocol->request($request, $proxy, \&callback, 1024);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Dispatches a request over the protocol, and returns a response
|
|
object. This method needs to be overridden in subclasses. Refer to
|
|
LWP::UserAgent for description of the arguments.
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>collect</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $res = $prot->collect(undef, $response, $collector); # stored in $response
|
|
my $res = $prot->collect($filename, $response, $collector);
|
|
my $res = $prot->collect(sub { ... }, $response, $collector);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Collect the content of a request, and process it appropriately into a scalar,
|
|
file, or by calling a callback. If the first parameter is undefined, then the
|
|
content is stored within the <TT>$response</TT>. If it's a simple scalar, then it's
|
|
interpreted as a file name and the content is written to this file. If it's a
|
|
code reference, then content is passed to this routine.
|
|
<P>
|
|
|
|
The collector is a routine that will be called and which is
|
|
responsible for returning pieces (as ref to scalar) of the content to
|
|
process. The <TT>$collector</TT> signals <TT>"EOF"</TT> by returning a reference to an
|
|
empty string.
|
|
<P>
|
|
|
|
The return value is the HTTP::Response object reference.
|
|
<P>
|
|
|
|
<B>Note:</B> We will only use the callback or file argument if
|
|
<TT>"$response->is_success()"</TT>. This avoids sending content data for
|
|
redirects and authentication responses to the callback which would be
|
|
confusing.
|
|
<A NAME="lbAK"> </A>
|
|
<H3>collect_once</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$prot->collect_once($arg, $response, $content)
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Can be called when the whole response content is available as content. This
|
|
will invoke ``collect'' in LWP::Protocol with a collector callback that
|
|
returns a reference to <TT>$content</TT> the first time and an empty string the
|
|
next.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
Inspect the <I>LWP/Protocol/file.pm</I> and <I>LWP/Protocol/http.pm</I> files
|
|
for examples of usage.
|
|
<A NAME="lbAM"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
|
|
|
|
Copyright 1995-2001 Gisle Aas.
|
|
<P>
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the same terms as Perl itself.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="2"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="3"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="4"><A HREF="#lbAE">METHODS</A><DD>
|
|
<DL>
|
|
<DT id="5"><A HREF="#lbAF">new</A><DD>
|
|
<DT id="6"><A HREF="#lbAG">create</A><DD>
|
|
<DT id="7"><A HREF="#lbAH">implementor</A><DD>
|
|
<DT id="8"><A HREF="#lbAI">request</A><DD>
|
|
<DT id="9"><A HREF="#lbAJ">collect</A><DD>
|
|
<DT id="10"><A HREF="#lbAK">collect_once</A><DD>
|
|
</DL>
|
|
<DT id="11"><A HREF="#lbAL">SEE ALSO</A><DD>
|
|
<DT id="12"><A HREF="#lbAM">COPYRIGHT</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:47 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|