The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
libwww-perl-5b13
River stage four • 2163 direct dependents • 6200 total dependents
167 ++
/ 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 an 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 sub classes need to override the request() method which is used to service a request for that specific protocol. 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

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);

Dispactches a request over the protocol, and returns a response object. This method needs to be overridden in subclasses. Referer to LWP::UserAgent for description of the arguments.

timeout($seconds)

Get and set the timeout value in seconds

use_alarm($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 or file argument if $response->is_success(). This avoids sendig content data for redirects and authentization responses to the callback which would be confusing.