/ 
libwww-perl-5b6
River stage four • 2193 direct dependents • 6265 total dependents
/ LWP::Protocol

NAME

LWP::Protocol - Virtual base class for LWP protocols

DESCRIPTION

This class is the parent for all access method supported by the LWP library. It is used internally in the library.

When creating an instance of this class using LWP::Protocol::new() you pass a URL, and you get a initialised subclass appropriate for that access method. In other words, the constructor for this class calls the constructor for one of its subclasses;

The LWP::Protocol classes need to override the request() function which is used to request service for an access method. The overridden method can make use of the collect() function to collect together chunks of data received.

SEE ALSO

Inspect the LWP/Protocol/file.pm and LWP/Protocol/http.pm files for examples of usage.

METHODS AND FUNCTIONS

new

The LWP::Protocol constructor is inherited by subclasses. As this is a virtual base class this method should not be called like:

$prot = new LWP::Protocol()

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.

LWP::Protocol::implementor

LWP::Protocol::implementor($scheme);
LWP::Protocol::implementor($scheme, $class);

Get and/or set implementor class for a scheme. Returns '' if the specified scheme is not supported.

request(...)

$response = $protocol->request($request, $proxy, undef);
$response = $protocol->request($request, $proxy, '/tmp/sss');
$response = $protocol->request($request, $proxy, \&callback, 1024);

Dispactches a request over the protocol, and returns a response object. This method needs to be overridden in subclasses.

timeout($seconds)

Get and set the timeout value in seconds

useAlarm($yesno)

Indicates if the library is allowed to use the core alarm() function to implement timeouts.

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.

Note: We will only use the callback if $response->isSuccess(). This avoids sendig content data for redirects and authentization responses to the callback which would be confusing.