lib::LWP::ProtoUser3Contributed Perl Documenlib::LWP::Protocol(3)NAMELWP::Protocol - Base class for LWP protocols
SYNOPSIS
package LWP::Protocol::foo;
require LWP::Protocol;
@ISA=qw(LWP::Protocol);
DESCRIPTION
This class is used a the base class for all protocol
implementations supported by the LWP library.
When creating an instance of this class using
LWP::Protocol::create($url), and you get an initialised
subclass appropriate for that access method. In other
words, the LWP::Protocol::create() function calls the
constructor for one of its subclasses.
All derived LWP::Protocol classes need to override the
request() method which is used to service a request. The
overridden method can make use of the collect() function
to collect together chunks of data as it is received.
SEE ALSO
Inspect the LWP/Protocol/file.pm and LWP/Protocol/http.pm
files for examples of usage.
METHODS AND FUNCTIONS
$prot = new HTTP::Protocol;
The LWP::Protocol constructor is inherited by subclasses.
As this is a virtual base class this method should not be
called directly.
$prot = LWP::Protocol::create($url)
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.
$class = LWP::Protocol::implementor($scheme, [$class])
Get and/or set implementor class for a scheme. Returns ''
if the specified scheme is not supported.
$prot->request(...)
$response = $protocol->request($request, $proxy, undef);
$response = $protocol->request($request, $proxy, '/tmp/sss');
$response = $protocol->request($request, $proxy, \&callback, 1024);
24/Aug/1997 perl 5.005, patch 03 1
lib::LWP::ProtoUser3Contributed Perl Documenlib::LWP::Protocol(3)
Dispactches a request over the protocol, and returns a
response object. This method needs to be overridden in
subclasses. Referer to the LWP::UserAgent manpage for
description of the arguments.
$prot->timeout($seconds)
Get and set the timeout value in seconds
$prot->use_alarm($yesno)
Indicates if the library is allowed to use the core
alarm() function to implement timeouts.
$prot->parse_head($yesno)
Should we initialize response headers from the <head>
section of HTML documents.
$prot->collect($arg, $response, $collector)
Called to collect the content of a request, and process it
appropriately into a scalar, file, or by calling a
callback. If $arg is undefined, then the content is
stored within the $response. If $arg is a simple scalar,
then $arg is interpreted as a file name and the content is
written to this file. If $arg is a reference to a
routine, then content is passed to this routine.
The $collector is a routine that will be called and which
is reponsible for returning pieces (as ref to scalar) of
the content to process. The $collector signals EOF by
returning a reference to an empty sting.
The return value from collect() is the $response object
reference.
Note: We will only use the callback or file argument if
$response->is_success(). This avoids sendig content data
for redirects and authentization responses to the callback
which would be confusing.
$prot->collect_once($arg, $response, $content)
Can be called when the whole response content is available
as $content. This will invoke collect() with a collector
callback that returns a reference to $content the first
time and an empty string the next.
24/Aug/1997 perl 5.005, patch 03 2
lib::LWP::ProtoUser3Contributed Perl Documenlib::LWP::Protocol(3)24/Aug/1997 perl 5.005, patch 03 3