GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
LWP::Protocol(3) User Contributed Perl Documentation LWP::Protocol(3)

LWP::Protocol - Base class for LWP protocols

 package LWP::Protocol::foo;
 use parent qw(LWP::Protocol);

This class is used as 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 initialized subclass appropriate for that access method. In other words, the "create" in LWP::Protocol 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()" method to collect together chunks of data as it is received.

The following methods and functions are provided:

    my $prot = LWP::Protocol->new();

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

    my $prot = LWP::Protocol::create($scheme)

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.

    my $class = LWP::Protocol::implementor($scheme, [$class])

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

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

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.

    my $res = $prot->collect(undef, $response, $collector); # stored in $response
    my $res = $prot->collect($filename, $response, $collector);
    my $res = $prot->collect(sub { ... }, $response, $collector);

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 $response. 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.

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 $collector signals "EOF" by returning a reference to an empty string.

The return value is the HTTP::Response object reference.

Note: We will only use the callback or file argument if "$response->is_success()". This avoids sending content data for redirects and authentication 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" in LWP::Protocol with a collector callback that returns a reference to $content the first time and an empty string the next.

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

Copyright 1995-2001 Gisle Aas.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

2022-01-21 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.