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 parent 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() method to collect together chunks of data as
24       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           $response = $protocol->request($request, $proxy, $fh);
54
55       Dispatches a request over the protocol, and returns a response object.
56       This method needs to be overridden in subclasses.  Refer to
57       LWP::UserAgent for description of the arguments.
58
59   collect
60           my $res = $prot->collect(undef, $response, $collector); # stored in $response
61           my $res = $prot->collect($filename, $response, $collector);
62           my $res = $prot->collect(sub { ... }, $response, $collector);
63
64       Collect the content of a request, and process it appropriately into a
65       scalar, file, or by calling a callback. If the first parameter is
66       undefined, then the content is stored within the $response. If it's a
67       simple scalar, then it's interpreted as a file name and the content is
68       written to this file.  If it's a code reference, then content is passed
69       to this routine.  If it is a filehandle, or similar, such as a
70       File::Temp object, content will be written to it.
71
72       The collector is a routine that will be called and which is responsible
73       for returning pieces (as ref to scalar) of the content to process.  The
74       $collector signals "EOF" by returning a reference to an empty string.
75
76       The return value is the HTTP::Response object reference.
77
78       Note: We will only use the callback or file argument if
79       "$response->is_success()".  This avoids sending content data for
80       redirects and authentication responses to the callback which would be
81       confusing.
82
83   collect_once
84           $prot->collect_once($arg, $response, $content)
85
86       Can be called when the whole response content is available as content.
87       This will invoke "collect" in LWP::Protocol with a collector callback
88       that returns a reference to $content the first time and an empty string
89       the next.
90

SEE ALSO

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

96       Copyright 1995-2001 Gisle Aas.
97
98       This library is free software; you can redistribute it and/or modify it
99       under the same terms as Perl itself.
100
101
102
103perl v5.36.0                      2023-03-01                  LWP::Protocol(3)
Impressum