1LWP::Protocol(3)      User Contributed Perl Documentation     LWP::Protocol(3)
2
3
4

NAME

6       LWP::Protocol - Base class for LWP protocols
7

SYNOPSIS

9        package LWP::Protocol::foo;
10        use base qw(LWP::Protocol);
11

DESCRIPTION

13       This class is used as the base class for all protocol implementations
14       supported by the LWP library.
15
16       When creating an instance of this class using
17       "LWP::Protocol::create($url)", and you get an initialized subclass
18       appropriate for that access method. In other words, the "create" in
19       LWP::Protocol function calls the constructor for one of its subclasses.
20
21       All derived "LWP::Protocol" classes need to override the request()
22       method which is used to service a request. The overridden method can
23       make use of the collect() function to collect together chunks of data
24       as it is received.
25

METHODS

27       The following methods and functions are provided:
28
29   new
30           my $prot = LWP::Protocol->new();
31
32       The LWP::Protocol constructor is inherited by subclasses. As this is a
33       virtual base class this method should not be called directly.
34
35   create
36           my $prot = LWP::Protocol::create($scheme)
37
38       Create an object of the class implementing the protocol to handle the
39       given scheme. This is a function, not a method. It is more an object
40       factory than a constructor. This is the function user agents should use
41       to access protocols.
42
43   implementor
44           my $class = LWP::Protocol::implementor($scheme, [$class])
45
46       Get and/or set implementor class for a scheme.  Returns '' if the
47       specified scheme is not supported.
48
49   request
50           $response = $protocol->request($request, $proxy, undef);
51           $response = $protocol->request($request, $proxy, '/tmp/sss');
52           $response = $protocol->request($request, $proxy, \&callback, 1024);
53
54       Dispatches a request over the protocol, and returns a response object.
55       This method needs to be overridden in subclasses.  Refer to
56       LWP::UserAgent for description of the arguments.
57
58   collect
59           my $res = $prot->collect(undef, $response, $collector); # stored in $response
60           my $res = $prot->collect($filename, $response, $collector);
61           my $res = $prot->collect(sub { ... }, $response, $collector);
62
63       Collect the content of a request, and process it appropriately into a
64       scalar, file, or by calling a callback. If the first parameter is
65       undefined, then the content is stored within the $response. If it's a
66       simple scalar, then it's interpreted as a file name and the content is
67       written to this file.  If it's a code reference, then content is passed
68       to this routine.
69
70       The collector is a routine that will be called and which is responsible
71       for returning pieces (as ref to scalar) of the content to process.  The
72       $collector signals "EOF" by returning a reference to an empty string.
73
74       The return value is the HTTP::Response object reference.
75
76       Note: We will only use the callback or file argument if
77       "$response->is_success()".  This avoids sending content data for
78       redirects and authentication responses to the callback which would be
79       confusing.
80
81   collect_once
82           $prot->collect_once($arg, $response, $content)
83
84       Can be called when the whole response content is available as content.
85       This will invoke "collect" in LWP::Protocol with a collector callback
86       that returns a reference to $content the first time and an empty string
87       the next.
88

SEE ALSO

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

94       Copyright 1995-2001 Gisle Aas.
95
96       This library is free software; you can redistribute it and/or modify it
97       under the same terms as Perl itself.
98
99
100
101perl v5.30.2                      2020-04-15                  LWP::Protocol(3)
Impressum